keyd
v2.4.3
Linux lacks a good key remapping solution. In order to achieve satisfactory results a medley of tools need to be employed (e.g xcape, xmodmap) with the end result often being tethered to a specified environment (X11). keyd attempts to solve this problem by providing a flexible system wide daemon which remaps keys using kernel level input primitives (evdev, uinput).
The config format has undergone several iterations since the first release. For those migrating their configs from v1 it is best to reread the man page.
See also: changelog.
keyd has several unique features many of which are traditionally only found in custom keyboard firmware like QMK as well as some which are unique to keyd.
Some of the more interesting ones include:
C-1 without breaking modifier semantics.Note: master serves as the development branch, things may occasionally break between releases. Releases are tagged, and should be considered stable.
git clone https://github.com/rvaiya/keyd
cd keyd
make && sudo make install
sudo systemctl enable keyd && sudo systemctl start keyd
Install and start keyd (e.g sudo systemctl enable keyd)
Put the following in /etc/keyd/default.conf:
[ids]
*
[main]
# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)
# Remaps the escape key to capslock
esc = capslock
Key names can be obtained by using the keyd monitor command. Note that while keyd is running, the output of this
command will correspond to keyd's output. The original input events can be seen by first stopping keyd and then
running the command. See the man page for more details.
Run sudo keyd reload to reload the config set.
See the man page (man keyd) for a more comprehensive description.
Config errors will appear in the log output and can be accessed in the usual
way using your system's service manager (e.g sudo journalctl -eu keyd).
Note: It is possible to render your machine unusable with a bad config file.
Should you find yourself in this position, the special key sequence
backspace+escape+enter should cause keyd to terminate.
Some mice (e.g the Logitech MX Master) are capable of emitting keys and are consequently matched by the wildcard id. It may be necessary to explicitly blacklist these.
Add yourself to the keyd group:
usermod -aG keyd <user>
Populate ~/.config/keyd/app.conf:
E.G
[alacritty]
alt.] = macro(C-g n)
alt.[ = macro(C-g p)
[chromium]
alt.[ = C-S-tab
alt.] = macro(C-tab)
Run:
keyd-application-mapper
You will probably want to put keyd-application-mapper -d somewhere in your
display server initialization logic (e.g ~/.xinitrc) unless you are running Gnome.
See the man page for more details.
Experimental support for single board computers (SBCs) via usb-gadget has been added courtesy of Giorgi Chavchanidze.
See usb-gadget.md for details.
Third party packages for the some distributions also exist. If you wish to add yours to the list please file a PR. These are kindly maintained by community members, no personal responsibility is taken for them.
keyd package maintained by @jirutka.
Arch Linux package maintained by Arch packagers.
Experimental keyd and keyd-application-mapper packages can be found in the
CI build artifacts of the work-in-progress Debian package
repository:
Any Debian Developer who is willing to review the debianization effort and sponsor its upload is encouraged to contact @rhansen (also see the Debian ITP bug).
COPR package maintained by @alternateved.
opensuse package maintained by @bubbleguuum.
Easy install with sudo zypper in keyd.
Experimental keyd and keyd-application-mapper packages can be found in the
ppa:keyd-team/ppa
archive.
If you wish to help maintain this PPA, please contact @rhansen.
[ids]
*
[main]
leftshift = oneshot(shift)
capslock = overload(symbols, esc)
[symbols]
d = ~
f = /
...
Many users will probably not be interested in taking full advantage of keyd. For those who seek simple quality of life improvements I can recommend the following config:
[ids]
*
[main]
shift = oneshot(shift)
meta = oneshot(meta)
control = oneshot(control)
leftalt = oneshot(alt)
rightalt = oneshot(altgr)
capslock = overload(control, esc)
insert = S-insert
This overloads the capslock key to function as both escape (when tapped) and control (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce the letter A you can now simply tap shift and then a instead of having to hold it. Finally it remaps insert to S-insert (paste on X11).
xmodmap and friends are display server level tools with limited functionality. keyd is a system level solution which implements advanced features like layering and oneshot modifiers. While some X tools offer similar functionality I am not aware of anything that is as flexible as keyd.
keyd was written several years ago to allow me to easily experiment with different layouts on my growing keyboard collection. At the time kmonad did not exist and custom keyboard firmware like QMK (which inspired keyd) was the only way to get comparable features. I became aware of kmonad after having published keyd. While kmonad is a fine project with similar goals, it takes a different approach and has a different design philosophy.
Notably keyd was written entirely in C with performance and simplicitly in mind and will likely never be as configurable as kmonad (which is extensible in Haskell). Having said that, it supplies (in the author's opinion) the most valuable features in less than 2000 lines of C while providing a simple language agnostic config format.
If you feel something is missing or find a bug you are welcome to file an issue on github. keyd has a minimalist (but sane) design philosophy which intentionally omits certain features (e.g execing arbitrary executables as root). Things which already exist in custom keyboard firmware like QMK are good candidates for inclusion.
See CONTRIBUTING. IRC Channel: #keyd on oftc
