keyd Documentation

To set up a basic configuration (e.g., mapping Caps Lock to Escape on tap and Control on hold):

1. Ensure keyd is installed and running (sudo systemctl enable --now keyd).
2. Create or edit /etc/keyd/default.conf.
3. Add your configuration rules.
4. Reload the configuration to apply changes.

You can use keyd monitor to find the exact names of your keys. Note that while keyd is running, keyd monitor shows the output of keyd; to see original hardware events, stop keyd first.

Note: If you use a mouse that emits keys (like Logitech MX Master), you may need to explicitly blacklist its ID in the [ids] section to prevent it from being caught by the wildcard *.

[ids]

*

[main]

# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)

# Remaps the escape key to capslock
esc = capslock

keyd supports experimental application-specific remapping (e.g., different shortcuts for Alacritty or Chromium).

1. Add your user to the keyd group: usermod -aG keyd <user>
2. Create a configuration file at ~/.config/keyd/app.conf.
3. Define mappings using the application name as the section header.
4. Run the keyd-application-mapper daemon.

Integration: For non-Gnome environments, you should add keyd-application-mapper -d to your display server initialization (e.g., ~/.xinitrc).

usermod -aG keyd <user>

# Example ~/.config/keyd/app.conf content:
[alacritty]
alt.] = macro(C-g n)
alt.[ = macro(C-g p)

[chromium]
alt.[ = C-S-tab
alt.] = macro(C-tab)

# Run the mapper
keyd-application-mapper

To build and install keyd with the usb-gadget virtual keyboard driver (VKBD) enabled, follow these steps. This requires building from source using the VKBD=usb-gadget flag.

After installation, you must enable and start both the keyd-usb-gadget service and the standard keyd service.

git clone https://github.com/rvaiya/keyd
cd keyd
make VKBD=usb-gadget && sudo make install VKBD=usb-gadget
sudo systemctl enable keyd-usb-gadget && sudo systemctl start keyd-usb-gadget
sudo systemctl enable keyd && sudo systemctl start keyd

To install keyd from source, you need a C compiler and Linux kernel headers. Follow these steps:

1. Clone the repository.
2. Build and install using make.
3. Enable and start the keyd systemd service.

Warning: A bad configuration file can make your machine unusable. If this happens, press the special key sequence backspace+escape+enter to terminate keyd immediately.

git clone https://github.com/rvaiya/keyd
cd keyd
make && sudo make install
sudo systemctl enable --now keyd

keyd is available in several official and community repositories:

• Debian 13+ / Ubuntu 25.04+: sudo apt install keyd (For older Ubuntu, use ppa:keyd-team/ppa)
• openSUSE: sudo zypper in keyd
• Void Linux: sudo xbps-install -Su keyd
• Arch Linux: Available in extra repository.
• Alpine Linux: Available via apk.
• Fedora: Available via COPR.
• Gentoo: Available via GURU.

In version 2.3.0-rc and later, layers are fully transparent. Bindings are resolved based on activation order, with [main] being the default active layer.

Modifiers apply to all bindings except for those associated with the active layer. This allows you to pair modifiers with layer entries without needing complex layer nesting. For example, if a layer is activated via a key, modifiers applied to that key will not affect the bindings within that layer, but modifiers applied externally will.

The following management features have been removed in recent versions:

• The -d flag (daemonization) has been eliminated; use your init system to manage the daemon.
• reload on SIGUSR1 has been eliminated; perform a full restart of the service instead.

Because keyd creates a virtual device that combines internal and external keyboards, libinput's 'disable-while-typing' feature may fail to distinguish them, causing trackpad issues.

To fix this, tell libinput to treat the keyd virtual device as internal by creating or editing /etc/libinput/local-overrides.quirks with the following content:

[Serial Keyboards]

MatchUdevType=keyboard
MatchName=keyd*keyboard
AttrKeyboardIntegration=internal