> For the complete documentation index, see [llms.txt](https://docs.keyboardswitch.tolik.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keyboardswitch.tolik.io/4.4/usage-guides/installation.md).

# 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. If your computer runs on the x64 architecture, then you should get the *x64* installer. If your computer runs on the Arm architecture, then you should get the *arm64* installer. If you're not sure, then you most likely need the *x64* installer.

After installing the app, the installer will start the settings app. 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 can configure the character mappings (you can read more about it in the next article) and 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.

### Uninstalling the App

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

The uninstaller will not delete the app's configuration. If you want to delete it, then go to your local app data folder, and delete the *KeyboardSwitch* folder.

The uninstaller will also 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.

### 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.4.0-x64-win.zip* or *KeyboardSwitch-4.4.0-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 your 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 Apple CPU (e.g. M1), then you should get the *arm64* package. If your computer runs on an Intel CPU, then you should get the *x86\_64* package.

The installer will install multiple things:

* The Keyboard Switch Service app will be put into the */Library/Application Support* 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 can configure the character mappings (you can read more about it in the next article) and 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.4.0.pkg* file, and Keyboard Switch will be removed.

If you want to delete the app's configuration as well, then delete the *\[home]/Library/Application Support/Keyboard Switch* folder. You can also delete the app's log files by deleting the *\[home]/Library/Logs/Keyboard Switch* folder.

## Linux

### Installing the App

#### Prerequisites

There are several prerequisites for running the app on Linux:

* X11 or Wayland though the latter is supported only on GNOME and KDE Plasma.
* X Keyboard Extension (XKB) which is available by default on both X11 and Wayland.
* libxkbcommon which is usually installed by default.
* The `acl` package which is usually installed by default.
* [wl-clipboard](https://github.com/bugaevc/wl-clipboard) (Wayand only) – used to copy and paste text on Wayland.
* [xsel](https://github.com/kfish/xsel) (X11 only, optional) – used to copy and paste text on X11 if the corresponding setting is enabled.
* 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).

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

Starting with version 4.2, Keyboard Switch uses native clipboard integration on X11 by default. This works well on newer desktop environments but doesn't work well on older versions. If you notice that Keyboard Switch doesn't work well on your system, then you can switch to using xsel instead. xsel must be installed manually though, and the service app must be restarted when this setting is changed. On Wayland, there is no native clipboard integration, the application always uses wl-clipboard.

[Click here](https://github.com/TolikPylypchuk/KeyboardSwitch/issues/129) 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 before opening Keyboard Switch Settings. 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, Rocky, Fedora and others (but not Linux Mint). If you're using X11, Press <kbd>Alt</kbd>+<kbd>F2</kbd>, then type <kbd>r</kbd> and press <kbd>Enter</kbd> – this will restart GNOME. If you're using Wayland (which is most probably the case on newer versions of GNOME), then you'll have to log out and log back in.
{% 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 has the following dependencies:

* `acl`
* `libxkbcommon0`
* `wl-clipboard` (as a recommended dependency, installed by default)
* `xsel` (as an optional dependency, not installed by default)

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.

#### Using an RPM Package

If you're running a RHEL-based distribution (e.g., Rocky Linux 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 has the following dependencies:

* `acl`&#x20;
* `libxkbcommon.so.0()(64bit)` (libxkbcommon is provided by different packages on RHEL-based distros and SUSE, so this form takes care of both package names)
* `wl-clipboard` (as a recommended dependency, installed by default)
* `xsel` (as a suggested dependency, not installed by default)

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.

#### Using a Tar Archive

Keyboard Switch is also available as a *tar.gz* file. 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* does the following:

* creates the `keyboard-switch` system group and grants it access to the input system if the group doesn't exist;
* sets the Keyboard Switch executable to belong to that group so that it has access the input system;
* adds the settings app to the list of installed apps.

The first two items require a one-time root access. Do not run *install.sh* with `sudo` - it will run the needed commands with `sudo` itself which will only require that you enter a password.

*uninstall.sh* removes the app from the list of installed apps.

Apart from the one-time setup of the input system access for Keyboard Switch, these scripts make changes only for the current user.

Both the *x64* and *arm64* versions are available.

The following scripts assume that the */opt* directory is writable. Substitute *x64* with *arm64* if needed.

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

```bash
sudo apt update
sudo apt install wl-clipboard # Install wl-clipboard which is required on Wayland
sudo apt install xsel # Optional, install only if you plan to use the xsel setting on X11
tar -xzf keyboard-switch-4.4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
# Enter your password when the sudo prompt appears
```

Here are the steps required for installing the app on RHEL, Fedora, or Rocky Linux:

```bash
sudo dnf install wl-clipboard # Install wl-clipboard which is required on Wayland
sudo dnf install xsel # Optional, install only if you plan to use the xsel setting on X11
tar -xzf keyboard-switch-4.4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
# Enter your password when the sudo prompt appears
```

Here are the steps required for installing the app on SUSE:

```bash
sudo zypper install wl-clipboard # Install wl-clipboard which is required on Wayland
sudo zypper install xsel # Optional, install only if you plan to use the xsel setting on X11
tar -xzf keyboard-switch-4.4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
# Enter your password when the sudo prompt appears
```

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

```bash
sudo pacman -S wl-clipboard # Install wl-clipboard which is required on Wayland
sudo pacman -S xsel # Optional, install only if you plan to use the xsel setting on X11
tar -xzf keyboard-switch-4.4.0-x64.tar.gz -C /opt
cd /opt/keyboard-switch
./install.sh
# Enter your password when the sudo prompt appears
```

### 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 there are several ways to do that:

* For deb packages, you can run `apt remove` with the `--purge` option.
* For *tar.gz* files, you can run `uninstall.sh` with the `--purge` option.
* You can delete the *\~/.config/keyboard-switch* directory manually.

There is no way to delete the app configuration automatically for RPM packages.

The `keyboard-switch` group is not removed automatically. If you want to remove this group and its accesses as well, run the following commands:

```bash
sudo rm /etc/udev/rules.d/99-keyboard-switch.rules
udevadm control --reload-rules
sudo groupdel keyboard-switch
```