Key Remapping in Linux — 2021 Edition
Trying to find the right key remapper for your Linux laptop or desktop? The landscape has changed a lot in two years, and there are now some excellent options.
I’ve spent the past week writing experimental software, researching a dozen or so open source key remapping solutions (see table below), and corresponding with some of these projects’ authors.
It has become clear to me that in this niche especially, the free-culture movement embraces variety and experimentation. But if you’re looking to choose the right tool for you, don’t let the breadth of choice weary you — there are now 3 or so excellent options rising to the top.
Note to self: don’t write my own key remapping software.
Some of the big questions you need to have answers for when evaluating the options are:
- Do I need Wayland support?
- Do I need to change the key map depending on what window/app is active?
- Do I need advanced configuration, like layer toggling, or nuanced control over modifier states?
As of today, Wayland’s support for both key remapping and active window querying (e.g. what xdotool would provide for X11 users) is very weak. While there are some possible solutions on the horizon, it looks like Wayland’s security model makes it uncertain how developers should write software to get at window data (“which window is active?”) or control input devices (i.e. there is no xmodmap or setxkbmap equivalent for Wayland). My sense is we will need to wait another year or more before this gets sorted out.
1. The Easy Option (X11 only)— autokey
I’ll cut through the rest of the analysis and say right up front that if you’re running Linux’s traditional window system (X11) and you just want an easy, established solution to the key remapping problem, you should probably go with autokey.
Autokey has a graphical user interface, has easy-to-configure basic remapping, and enables Python scripting for the more advanced use cases. It has a tray icon, so you can access it and know it’s running. It also watches for changes to the currently active window and can differentiate apps you use, which means you can send different remapped keys to each app, depending on the app you’re focused on.
Install autokey with your system’s package manager. On Pop!_OS you can install it in the Pop shop. On another flavor of Ubuntu, sudo apt install autokey-gtk (typed into the terminal) should do the trick.
2. For Advanced Use Cases — keyd
In terms of balancing ease of configuration with power, keyd comes with my highest recommendation. While it isn’t as easy to use as autokey, it is still very easy to configure with a single text file (/etc/keyd/default.cfg).
Keyd is among what I would consider the “new generation” of key re-mapping services that use the kernel’s user-space input events library (evdev). This means it works on Wayland as well as X11, and operates “in the background” as a system service, rather than “in the foreground” at the X11 level or with a visible taskbar (like autokey does).
I discovered keyd while looking for a way to configure my Linux user interface to behave more like the Mac OS way that I’m used to. In a long conversation with the author of keyd (who was kind, smart, and responsive — the best kind of experience you can hope for when speaking with a volunteer), we discovered a way to handle the most vexing problem: sending different key sequences when in “app switch mode” (Cmd+Tab on a Mac) vs regular mode. This basically entails keeping state and switching modes while still in a modifier pressed state. The flexibility and power are quite impressive, even while keeping the configuration format easy to reason about.
In short, keyd is the option I’d recommend to most people who have an “advanced use case” (or edge case) that autokey is unable to handle, or if you’re using Wayland where autokey won’t work.
3. The Keyboard Fanatic Option — kmonad
There’s a subset of people that I hope I’m not offending when I call them “keyboard fanatics”. These are the fans who’ve built their own 60% mechanical keyboards, written their own firmware (e.g. QMK), know what a teensy or esp32 board is, or have otherwise gone all the way when customizing their typing experience. If you’re in the QMK club, you probably already know about kmonad.
Kmonad is also in the “new generation” of key remappers that use evdev to transform keypresses even before X11 or Wayland becomes aware of an input event. It’s a beautiful piece of software, written in Haskell, that is by far the most configurable I’ve seen. It has it’s own lisp-like configuration file format for goodness sake!
Kmonad has the largest coder base, with over 40 software engineers contributing code to the repository. It also works on both Mac and Windows. Right now, installing kmonad is easy on any system but Ubuntu. Still, if you’re on Ubuntu, you can use the software if you compile and install it using Haskell Stack.
4. The Wayland Easy Option — key-mapper
Autokey is no longer alone as the king of easy configuration. key-mapper also has a nice, simple graphical interface; and, in addition to working in X11, it also supports Wayland.
Another valuable capability of key-mapper is its support for mouse events. You can combine and configure mouse buttons along with keys to arrive at a bespoke input system. While not as powerful as some of the other options (i.e. key-mapper has less flexibility with regard to modifier states and layers), I would still definitely recommend taking a look if “simple” and “Wayland” are top of your priority list.
The Alternative Options — kbct, hawck, & interception
If none of the above options suit you, you may want to try kbct, hawck, or interception.
Kbct
Kbct distinguishes itself by being written in Rust, and having a relatively simple configuration file format. It also does a great job explaining how the “new generation” of key remappers can work for both X11 and Wayland:
Hawck
Hawck is a sophisticated two-part daemon that prioritizes security and power. It separates root-level access on one side and user-level access on the other, making it possible to offer some security such as whitelisting keys for the scripts you write.
In addition, Hawck allows you to write scripts in a Lua-derived language for full-power customization. While similar in concept to Interception (below), it offers its scripting in a higher-level language, which means no compilation is needed and there are fewer steps to tweak and try new things.
Interception
Last but not least, if none of the above options work for you because you have a *really weird* use case where you need to code your own solution, I’d recommend checking out interception before you go write another key remapper from scratch.
This daemon does all of the “hard parts” of udev and evdev monitoring, handing binary data directly to your compiled C code’s stdin stream. There, you can keep track of state and transform the event stream in whatever wild way that you’d like. Interception also includes or links to several pre-built addons (C code) that do common things like switching escape for capslock.
If you’d like to install interception, there are packages for Arch, Void, Fedora, and Ubuntu.
Houmain/Keymapper
A late entry based on comments on this article, houmain/keymapper is another interesting option that you might consider. It has a similarly powerful configuration to keyd and offers a great deal of flexibility for what is a relatively simple file format.
Migrating from Mac OS to Linux
Mac OS is as strong as ever, but a trickle of software developers have been disenfranchised by Apple’s increasing demand for control over its hardware, which diminishes the importance of values like ownership, the right to repair, and free-culture.
If you find yourself in this camp and are looking to make the switch, there are some great options for you.
1. The Ready-made Mac-to-Linux Switcher: Kinto
The kinto project (kinto.sh) is a suite of tweaks that make a modern desktop Linux operating system behave a lot more like a Mac. Your muscle memory will be preserved, and possibly your sanity. While kinto does more than just key remapping, a large part of its role is handling the nuances of which app needs which key shortcuts to behave in a “Mac OS way”.
2. Just remap your keyboard
Your other option is to just remap the keyboard yourself. You’ll have the most control over your system and experience as you make the switch from Mac to Linux.
I’ve written a keyd config file that does a lot of what I expect from a keyboard, coming from 15 years on a MacBook Pro. If your background is similar, you might find it handy in your learning journey.
Key Remapping Software Comparison
Here’s a more detailed view of the options, with notes and features side-by-side:
You can check out the spreadsheet here (which may have changed since the screenshot was taken).
I hope you find the right solution for yourself!
Best regards.
