What is keyd?

keyd is a key remapping daemon for Linux that works at the kernel level. keyd remaps keys before any application sees them, making it one of the most reliable remapping solutions available on Linux.

This guide walks you through installing keyd from source, writing a basic configuration, and optionally running the setup script to apply a preset configuration and register keyd as an internal keyboard.

Prerequisites

Before starting, make sure make and a C compiler (cc) are installed on your system. These are build dependencies required to compile keyd from source.

Fedora

sudo dnf install make gcc

Debian/Ubuntu

sudo apt install make gcc

Arch

sudo pacman -S make gcc

If you would like to append everything in this guide quickly you can download and run this bash script after installing all prerequisites.

Installing keyd

keyd is not available in most distribution repositories, so it is installed by compiling from its GitHub source.

• Clone and build

  Create a directory for your installations and clone the repository into it:

  mkdir -p ~/Installations && cd ~/Installations
  git clone https://github.com/rvaiya/keyd
  cd keyd

  Then compile and install:

  make && sudo make install

• Enable the keyd service

  keyd runs as a systemd service. Enable and start it in one command:

  sudo systemctl enable --now keyd

  The --now flag both enables the service on boot and starts it immediately. You can verify it is running with:

  sudo systemctl status keyd

Configuring keyd

keyd reads its configuration from files placed in /etc/keyd/. The main configuration file is /etc/keyd/default.conf, and it applies to all keyboards by default.

Configuration file structure

A keyd config file has two required sections:

• [ids] — Specifies which keyboards the config applies to. Put a * to apply to all keyboards.
• [main] — Defines your key remappings and layers.

Here is a minimal example that demonstrates common remaps:

/etc/keyd/default.conf

# Keyd remap Copilot Key to Right Control and Double Shift to CAP
# place in /etc/keyd/

[ids]
*

[main]
capslock = backspace
leftshift+rightshift = capslock
leftshift+leftmeta+f23 = layer(control)

Mapping	What it does
capslock = backspace	Remaps Caps Lock to Backspace
leftshift+rightshift = capslock	Press both Shifts together to toggle Caps Lock
leftshift+leftmeta+f23 = layer(control)	Remaps a custom key combo (e.g. Copilot key) to act as Right Ctrl

Tips

You can find a full list of valid key names in the keyd man page:

man keyd

Applying a configuration

After writing your config, reload keyd to apply it immediately — no reboot needed:

sudo keyd reload

To verify the config was written correctly:

sudo cat /etc/keyd/default.conf

Registering keyd as an Internal Keyboard

This step is optional for desktops. It is primarily useful on laptops where you want palm rejection and other libinput heuristics to work with your remapped keyboard.

Create the directory if it does not exist, then write the quirks file:

sudo mkdir -p /etc/libinput
sudo nano /etc/libinput/local-overrides.quirks

Paste the following content:

/etc/libinput/local-overrides.quirks

# Libinput Local Quirks
# Save as /etc/libinput/local-overrides.quirks

[Recognise Keyd as Internal Keyboard]

MatchUdevType=keyboard
MatchName=keyd*keyboard
AttrKeyboardIntegration=internal

Save and close the file (Ctrl+O, Enter, Ctrl+X in nano).

Contributors

aier9500

Changelog

5/29/26, 4:15 AM

View All Changelog

• 21f6b-Stylisingon 5/29/26
• 304dc-typoon 5/29/26
• b5534-Change team name, fixing links.on 5/21/26
• 1fb69-Formatting and clarifying.on 5/13/26
• f544c-Restructuring assets and minor typo fixes.on 5/13/26
• 646aa-First iteration key remapping with keyd.on 5/12/26