# Installation

## Windows

### Using a Windows Installer

You can get the latest version of the app from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases). Download the *.msi* file and run it to install the app.

After installing the app, the installer will run the settings app. Currently it's not really optimized, so the startup time is not perfect; it can take a couple seconds for the app to get started. On the first start-up the settings app will configure the service to run when you log into the system.

When the settings app starts up you should configure the character mappings (you can read more about it in the next article). After you have configured the character mappings and possibly some other preferences, start the app using the *Start* button at the bottom of the window. That's it! Now you're ready to use the Keyboard Switch service.

Current only the x64 version can be installed with an installer. If you want the Arm64 version, then you should use a portable version or [build the installer yourself](/4.1/other/technical.md#building-the-windows-installer).

### Uninstalling the App

You can uninstall the app using the Settings app just like you would uninstall any other app.

{% hint style="warning" %}
The installer will not delete the registry entry which says that your app should start when you log in. If you want to keep your registry clean, you have to disable it in the settings app before uninstalling it.
{% endhint %}

Upon uninstallation the installer will ask whether you want to delete the app's configuration as well. If you choose not to delete the configuration, you can delete it later manually at any other time. It's stored under the user's local app data folder.

### Using the Portable Version

If you don't want to install the app (or can't), you can use the portable version of the app. It's literally the same as the installable version; there are no differences. Again, go to the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases) and download *KeyboardSwitch-4.1-x64-win.zip* or *KeyboardSwitch-4.1-arm64-win.zip*. If you're not sure which one you should download, then it's most probably x64. Extract the archive to anywhere you want and start *KeyboardSwitchSettings.exe*. It will configure the app to run when you log in just like the installed version. The configuration for the portable version is also stored under the user's local app data folder.

## macOS

### Installing the App

You can get the latest version of the app from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases). Download the *.pkg* file and run it to install the app. If your computer runs on an Intel CPU, then you should get the *x86\_64* package. If your computer runs on an Apple CPU (e.g. M1), then you should get the *arm64* package.

The installer will install multiple things:

* The Keyboard Switch Service app will be put into the */opt* folder – you shouldn't run or interact with this app directly
* The Keyboard Switch Settings app will be put into the */Applications* folder
* The descriptor file for running the service app when you log in will be put into the */Library/LaunchAgents* folder

After installing the app, open Keyboard Switch Settings – it should appear in the list of your apps.

Immediately upon opening the app, a dialog window should appear which says that Keyboard Switch would like to control this computer using accessibility features. The app needs this to listen to the magic key combination while running in the background, and without these permissions it won't work. This dialog will appear only when you're installing the app for the first time. If you have installed it previously, then macOS will most probably remember that you gave the app appropriate permissions.

Click the *Open System Preferences* button on the dialog window. Enable the *Keyboard Switch* item. Close System Preferences and go back to the Keyboard Switch Settings app.

If the dialog window didn't appear for some reason, then press the *Start* button at the bottom of the window. The service app will start and immediately stop, because it doesn't have the accessibility permissions, and the dialog window will appear again.

You should configure the character mappings (you can read more about it in the next article). After you have configured the character mappings and possibly some other preferences, start the app using the *Start* button. That's it! Now you're ready to use the Keyboard Switch service.

### Uninstalling the App

Many apps on macOS can be uninstalled just by deleting the app bundle from the */Applications* folder. This is not the case with Keyboard Switch. Multiple things should be done to remove it from the system. You shouldn't concern yourself with those things though – you should just run an uninstaller package, and it will remove Keyboard Switch.

As with the installer package, you can also get it from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases). Download and run the *KeyboardSwitchUninstaller-4.1.pkg* file, and Keyboard Switch will be removed.

If you want to delete the app's configuration as well, then delete the hidden *.keyboard-switch* folder in your home folder.

## Linux

### Installing the App

#### Prerequisites

There are several prerequisites for running the app on Linux:

* X11
* X Keyboard Extension (XKB) which is enabled by default
* X Test Extension – used to simulate pressing keys like <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> for you
* [xsel](https://github.com/kfish/xsel) – used to copy and paste text
* Bash – used to call xsel, but you don't need to have it as your default shell
* Freedesktop conventions – used to make the service app start when you log in, and to make the settings app appear in the list of your installed apps (not required for the app itself though)

Keyboard Switch doesn't support Wayland (even with XWayland).

The most popular desktop systems (at least GNOME, KDE Plasma, Cinnamon, and LXQt) all adhere to the Freedesktop protocols, so the last prerequisite is automatically available, unless you're running a very unusual setup.

[Click here](https://github.com/TolikPylypchuk/KeyboardSwitch/issues/76) to see the list of Linux distributions on which the app was tested.

{% hint style="warning" %}
If your desktop environment is GNOME, then you should restart it right after installation. If you're not sure which desktop environment you're using then it's most probably GNOME since it's the default one on Ubuntu, Debian, CentOS, Fedora and others (but not Linux Mint). Press <kbd>Alt</kbd>+<kbd>F2</kbd>, then type <kbd>r</kbd> and press <kbd>Enter</kbd>. This will restart GNOME.
{% endhint %}

#### Using a Deb Package

If you're running a Debian-based distribution (e.g., Ubuntu or Mint), then you can install Keyboard Switch using a deb package. You can get it from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases).

The package takes care of xsel and the X Test extension, so you don't need to install them yourself.

After installation, the settings app will be available in the list of installed apps, and the service app will be configured to run at login.

Both the *amd64* and *arm64* versions are available, but the latter is experimental.

#### Using an RPM Package

If you're running a RHEL-based distribution (e.g., CentOS or Fedora), or SUSE, then you can install Keyboard Switch using an RPM package. You can get it from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases).

The package takes care of xsel and the X Test extension, so you don't need to install them yourself.

{% hint style="info" %}
If you're using RHEL, CentOS, or Rocky Linux, then make sure that the EPEL repository is installed before installing Keyboard Switch. Otherwise, it won't be able to install xsel.
{% endhint %}

{% hint style="info" %}
SUSE may complain that it cannot find libXtst when installing the app using the RPM package. This is because the package is targeted for RHEL and derivatives. You can ignore this warning and proceed with installation, but make sure that libXtst6 is installed before starting the app.
{% endhint %}

After installation, the settings app will be available in the list of installed apps, and the service app will be configured to run at login.

Both the *x86\_64* and *aarch64* versions are available, but the latter is experimental.

#### Using a Tar Archive

Keyboard Switch is also available as a *tar.gz* fie. You can get it from the [releases page on GitHub](https://github.com/TolikPylypchuk/KeyboardSwitch/releases). You can then extract it to anywhere you like (e.g., into the */opt* directory). The deployed app includes two scripts – *install.sh* and *uninstall.sh*. *install.sh* adds the settings app to the list of installed apps. *uninstall.sh* deletes this configuration.

Both the *x64* and *arm64* versions are available, but the latter is experimental.

The following scripts assume that the */opt* directory is writable.

Here are the steps required for installing the app on Debian, Ubuntu, Linux Mint, etc.:

```
sudo apt update
sudo apt install xsel libxtst6  # Install xsel and the X Test Extension
tar -xzf keyboard-switch-4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
```

Here are the steps required for installing the app on RHEL, CentOS, Fedora, or Rocky Linux (use `yum` instead of `dnf` on older systems):

```
sudo dnf install epel-release  # Add the EPEL repository (not needed for Fedora)
sudo dnf install xsel          # Install xsel
sudo dnf install libXtst       # Install the X Test Extension
tar -xzf keyboard-switch-4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
```

Here are the steps required for installing the app on SUSE (you may need to add the X11:XOrg repository to install libXtst6):

```
sudo zypper install xsel      # Install xsel
sudo zypper install libXtst6  # Install the X Test Extension
tar -xzf keyboard-switch-4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
```

Here are the steps required for installing the app on Arch Linux:

```
sudo pacman -S xsel     # Install xsel
sudo pacman -S libxtst  # Install the X Test Extension
tar -xzf keyboard-switch-4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
```

### Uninstalling the App

For the deb and RPM packages, it's simple – just uninstall the package. For the *tar.gz* file, run the included *uninstall.sh* script, and delete the app's directory. If you want to delete the app's configuration as well, then delete the *\~/.keyboard-switch* directory.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keyboardswitch.tolik.io/4.1/usage-guides/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.