Key Mapper is a new GUI tool to remap your keyboard and mouse buttons on Linux desktops (it supports both X11 and Wayland).
The application supports per-device presets, and it allows using timed macros with the ability to repeat keys, wait between keys, hold a modifier while using a key, and more. Besides keyboards and mice, Key Mapper also comes with basic support for gamepads.
Other features include support for stopping any mappings and using system defaults for a device (using the
Apply Defaults button), and support for automatically loading presets on login for plugged in devices. Also, Key Mapper uses evdev to read keycodes and display them inside the application, so the user doesn’t have to do this manually.
The application does not support binding commands or scripts to keyboard or mouse buttons. For that, see this article from Linux Uprising.
For future releases, the developer plans to add support for mapping D-Pad and Joystick directions as buttons, automatically loading presets when a device is plugged in after login, and mapping a combined button press to a key.
How to remap keyboard and mouse buttons on Linux using Key Mapper
Using Key Mapper you can assign the action associated with a keyboard or mouse button to a different button. You may also use it to assign a macro (a sequence of button presses / actions) to a key.
The first time you run Key Mapper, you’ll want to select the device (mouse or keyboard) from the device dropdown. Choose a device, and you can start creating a new preset to easily remap your keyboard or mouse buttons.
Left-click in the
Key column, then press the keyboard key or mouse button you want to remap, and it will show up in the key box. In case this doesn’t work, you may need to click the
Apply Defaults button that’s displayed to the right-hand side of the device dropdown, and add the key after that.
After you enter the key you want to remap, it’s time to choose its mapping. Click inside the
Mapping cell corresponding to the key you want to remap, then start typing what you want to remap the button to. You can type the first few letters instead of the whole word, e.g. you can type “con” and a dropdown should show the available options, like
Once you’ve completed the mappings, click the
Save button. And finally, click
Apply to start using the new mappings. You must first
Save the new mappings, then click the
Apply button, or else the changes won’t have any effect!
It’s worth noting that using key combinations as mappings isn’t as straightforward as you may think, at least not using the latest release (because as I already mentioned, mapping a combined button press to a key is on the todo list). For example if you want to use
Ctrl + F1 as the mapping for a key, adding
control_l+f1 to the Key Mapper
Mapping column won’t work. Instead, you’ll need to use this as the mapping:
For how to use macros, check out the Key Mapper macro documentation, which also includes a few examples.
Download Key Mapper
Key Mapper can be installed easily on Debian / Ubuntu and Linux distributions based on these (like Linux Mint, Pop!_OS, Zorin OS, Elementary OS, etc.) by using the python3-key-mapper DEB package that can be downloaded from the application releases page.
Arch Linux and Manjaro users can install Key Mapper by using an AUR package.
You may also install Key Mapper using PIP as explained here, which works on any Linux distribution (I don’t recommend using PIP with
sudo though; also, on some Linux distributions you’ll need to use
pip3 instead of
pip, since this needs Python 3).
It’s very important to note that some devices might not be visible to Key Mapper unless you’re in the input user group. You can do this by either running
sudo usermod -a -G input $USER, or using the Key Mapper built-in permission fix command
sudo key-mapper-service --setup-permissions. After that you’ll need to log out and back in or restart your system, or else Key Mapper won’t work (note that in my case, a logout wasn’t enough so I had to reboot the system).
You might like: