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.

Quick append

If you would like to append everything in this guide quickly you can download the zip and run the keyd-setup.sh bash script after installing all prerequisites.

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

Installing keyd

keyd is not available in most distribution repositories, so it is installed via 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.

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.

You can also add extra sections for layers — for example, a [shift] section changes what keys do while Shift is held down.

Here is a minimal example that demonstrates common remaps:

/etc/keyd/default.conf

# Keyd remaps: Copilot key -> Ctrl; CapsLock -> Backspace,
# Shift + CapsLock -> CapsLock

# Place in /etc/keyd/default.conf

# Edit the file to your liking

[ids]
*

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

# Shift + capslock for capslock
[shift]
capslock = capslock

Mapping	What it does
leftshift+leftmeta+f23 = layer(control)	Remaps a custom key combo (e.g. Copilot key) to act as Ctrl
capslock = backspace	Remaps Caps Lock to Backspace
capslock = capslock (under [shift])	Hold Shift and press Caps Lock to toggle Caps Lock normally

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

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 features 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).

Verifying the registration

libinput is a library your desktop loads, not a background service — so there is no reload command for it. It re-reads its quirks files every time an input device is added, which means a reboot, or simply restarting keyd, re-applies them:

sudo systemctl restart keyd

Then test it: open any text field, start typing, and swipe on the touchpad while you type.

If the registration worked, the pointer stays put — your desktop now treats keyd's keyboard as internal and disables the touchpad while you type.

If nothing changes, log out and back in, then try the typing test again.

The quirks file must be world-readable

If the file ends up root-only (mode 600), it is silently ignored. Set it to mode 644:

sudo chmod 644 /etc/libinput/local-overrides.quirks

Contributors

aier9500

Changelog

7/13/26, 8:28 PM

View All Changelog

• 6eaee-docs(guides): set guide as canonical source, reconcile keyd/logitech drifton 7/13/26
• eb0c5-docs(guides): serve downloads same-origin as zips, not GitHub linkson 7/13/26
• 7150e-1. Fresh Editor → editors-choice.md. Verified as getfresh.dev (sinelaw/fresh) — Rust terminal editor, VS Code-feel. Install tabs: AUR fresh-editor-bin + official script. Several GitHub lookalikes exist; agent confirmed canonical project across independent sources. 2. Focus changer → aiers-gnome.md under Others, next to Tiling Shell. Link verified, plain 2-sentence description, no screenshot (none available). 3. Ghostty GNOME fix simplified — dropped alt+shift+arrow rebinds and the duplicate GNOME quick-append block. One master quick append now; GNOME section teaches clearing "Switch to workspace above/below" in Settings, gsettings fallback in :::details. Schema keys source-verified from gschema XML. 4. New keyd settings propagated — your root default.conf moved to resources/key-remapping-with-keyd/, stale header comment fixed (said double-shift→caps; body actually uses [shift] layer capslock = capslock). Guide example, mapping table, and keyd-setup.sh heredoc all synced; folder got first README.on 7/4/26
• 1f965-Testing neededon 6/23/26
• 62f81-missing libinput-tools dependency, fixedon 6/23/26
• a69b3-Fixingon 6/22/26
• 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