What Is keyd? The Beginner's Guide to Linux Keyboard Remapping (Layers, Overloads, One Config)

CodexFuse Team · 2026-11-04T13:29:43.071Z · 15 min read min read

What Is keyd, Exactly?

keyd is a system-wide key remapping daemon for Linux that rewrites your keystrokes at the kernel's input layer, below X11, Wayland, and even the plain text console, so a single configuration file controls what every key does everywhere on the machine. For keyd Linux users coming from X11-era tools, that single fact changes everything. If you have asked "what is keyd" while hunting for a way to remap keys on a modern Linux desktop, this is the tool: a small C daemon that sits between your physical keyboard and the kernel's input events, and applies your remaps before any application or display server ever sees them. The project's own description is deliberately plain — "A key remapping daemon for linux." — but that one line hides layers, tap-versus-hold key overloading, oneshot modifiers, macros, and per-application remapping in one coherent config format.

Before you remap anything, it helps to know what your keyboard is actually producing. Run your keys through a keyboard tester first: dead or ghosting keys are a hardware problem no remapper can fix, and keyd's monitor command will later show you the exact key names your system reports.

Why Do Linux Users Struggle to Remap Keys?

Linux users struggle to remap keys because the classic tools were built for X11, and X11 is no longer the whole story. The keyd README states the problem bluntly: "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)." When you switch to a Wayland compositor like Sway, Hyprland, or GNOME on Wayland, xmodmap stops working — it was an X11 tool talking to an X11 server that is no longer there. Tools like input-remapper exist for Wayland, but users report hitting walls with more complex logic, and display-server-specific tools cannot touch the virtual console you get with Ctrl+Alt+F3.

keyd solves this by refusing to live in userspace display-server land at all. It uses the kernel's own input primitives — evdev to read your keyboard and uinput to inject the remapped events back — so its keybindings "work identically across X11, Wayland compositors (Sway, Hyprland, GNOME), and even pure virtual consoles (TTYs)." Because remapping happens before any display server processes the input, there is no lag, no per-compositor config, and no keys that work in one app but not another. The project's stated goals are speed (a hand-tuned C input loop that processes keypresses in well under a millisecond), simplicity (an intuitive INI-style config), consistency (modifiers that play nicely with layers), and modularity (a UNIX-style core extensible through IPC).

How Do keyd Layers Actually Work?

A keyd layer is a complete alternate keymap that you switch on and off, and the shift key is the perfect mental model: hold Shift and every key on the keyboard means something different; release it and everything returns to normal. The man page defines it precisely: "A layer is a collection of bindings, each of which specifies the behaviour of a particular key. Multiple layers may be active at any given time, forming a stack of occluding keymaps consulted in activation order. The default layer is called main and is where common bindings should be defined." So your config always has a main layer — everything you do not explicitly rebind stays as-is — and you add custom layers on top of it.

Here is the canonical navigation-layer example from the official docs. Caps Lock becomes a layer key; while it is held, hjkl turn into arrow keys, and released, everything is normal again:

[main]
capslock = layer(nav)

[nav]
h = left
k = up
j = down
l = right

Modifiers get the same treatment by default: control, shift, meta, and alt are each bound to eponymously named layers, which is why modifier-plus-key combos behave sanely inside custom layers without extra work. Layers can even be composed — a layer named [control+alt] activates only when both constituents are active, so control+alt+h can produce left while control+h and alt+h keep their own meanings. Layer names accept a modifier set too, like [capslock:C], which activates the layer while adding the Control modifier to everything typed inside it. Each binding has the simple form key = action, key names are discoverable with keyd monitor, and chords are written with +: j+k = esc fires when j and k are struck together within the 50-millisecond chord window.

What Does overload() Do — Tap vs. Hold?

overload() gives one key two jobs: tap it for one action, hold it for another. The man page definition is exact: "Activates the given layer while held and executes on tap." The most famous use turns Caps Lock into the most useful key on the board — Escape when tapped, Control while held:

[ids]
*
[main]
# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)
# Remaps the escape key to capslock
esc = capslock

That two-line pattern — from keyd's own README quickstart — is why so many Linux developers install keyd in the first place. The rest of this guide has keyd explained from first principles, so nothing later assumes you already know the vocabulary. Vim users get Escape back under their pinky; everyone else gets a thumb-adjacent Control. The man page ships three refined variants for tricky cases: overloadt adds a hold timeout so letter keys struck in fast sequences do not misfire; overloadt2 additionally resolves as a hold if another key is tapped in between; and overloadi watches idle time, which powers homerow mods like a = overloadi(a, overloadt2(control, a, 200), 150) — the a key acts as Control only when you were already typing fast. First-class modifier overloading is listed as an explicit keyd feature, and it shows: these behaviors are one-liners, not scripts.

What Are Oneshot Modifiers?

Oneshot modifiers are sticky keys done right: tap a modifier once and it applies to just the next keypress, then releases itself. The definition: "If tapped, activate the supplied layer for the duration of the next keypress." This is a lifesaver for laptop keyboards and anyone with repetitive-strain pain — instead of chording Control+Shift+T with three fingers at once, you tap Control, tap Shift, then press T, each as a relaxed sequential tap. The man page pairs oneshot with a toggle to cover both styles: control = oneshot(control) in main, with control = toggle(control) inside the control layer so a deliberate hold still behaves like a held Control key.

The README's recommended starter config leans on oneshot for every modifier, which tells you how central the idea is:

[main]
shift = oneshot(shift)
meta = oneshot(meta)
control = oneshot(control)
leftalt = oneshot(alt)
rightalt = oneshot(altgr)
capslock = overload(control, esc)
insert = S-insert

A global oneshot_timeout option (default 0, meaning no timeout) can expire a tapped modifier after a set number of milliseconds if you worry about a stray tap lingering. Four ideas — layers, overloading, oneshot modifiers, and macros/chords — are the entire mental model, summarized here:

Which Linux Distros Can Install keyd?

keyd installs from source on any Linux distribution, and several major distros now ship it as a ready-made package. The README lists the from-source route first — git clone https://github.com/rvaiya/keyd, make && sudo make install, sudo systemctl enable --now keyd — followed by community-maintained packages for Alpine, Arch, Fedora (via COPR), Gentoo (via the GURU overlay), openSUSE, and Void. The convenient news for beginners: Debian 13 ("trixie") and later ship keyd directly (sudo apt install keyd), as does Ubuntu 25.04 ("plucky") and later, with a ppa:keyd-team/ppa backport archive for older Ubuntu releases. If you run keyd on a remote Linux box, pairing it with a solid understanding of VPS hosting helps — the same SSH-and-systemd fluency that runs your server applies to managing a system-wide input daemon.

How Do You Write Your First keyd Config?

You write your first keyd config in /etc/keyd/default.conf — one system-wide file that begins with an [ids] section and then lists your layers. The [ids] section decides which keyboards the file applies to: a lone * wildcard matches every keyboard keyd identifies, or you can target specific devices by ID (with k: and m: prefixes for keyboards and mice). A minimal but genuinely useful first config looks like this:

[ids]
*
[main]
capslock = overload(control, esc)
rightalt = oneshot(alt)

After saving, sudo keyd reload applies it instantly — keyd advertises "instantaneous remapping" as a feature, and there is no logout or reboot involved. Keep the file in version control: backing up /etc/keyd into a dotfiles repo with our Git beginner guide workflow means your perfect layout survives reinstalls. Config errors surface in the system journal (sudo journalctl -eu keyd), and device IDs plus valid key names come from keyd monitor.

How Do You Test a Config Without Breaking Your Keyboard?

You test a config with keyd check before it ever touches your live keyboard — and I verified this on a real build this run. I compiled keyd v2.6.0 from source on a Linux VM (build tag f564288, June 2026 master) and ran its built-in validator against the sample config above:

$ ./bin/keyd check cfg/default.conf
Parsing cfg/default.conf

No errors found.

The check command, added in v2.6.0, "exits with a non-zero return code if and only if any files fail validation," so it slots straight into scripts and dotfile installers. Feeding it a deliberately broken binding produced the expected rejection:

$ ./bin/keyd check cfg/bad.conf
Parsing cfg/bad.conf
	WARNING: cfg/bad.conf:4: invalid key or action

Beyond check, keyd monitor prints live key events so you can confirm each remap behaves as intended, and keyd monitor -t adds millisecond timings for debugging tap-versus-hold thresholds. If a config somehow slips past validation and renders your keyboard unusable, the README documents an escape hatch: the panic sequence backspace+escape+enter forces keyd to terminate. Mistakes are also diagnosable the usual Linux way through the service journal. If system-level Linux administration is still new territory for you, our Linux system guides cover the same journalctl-and-config-file habits this workflow depends on.

How Does Per-Application Remapping Work?

Per-application remapping works through a companion script, keyd-application-mapper, which watches window focus and overlays app-specific bindings on top of your global config. Its man page tagline says it all: "keyd-application-mapper - remap keys when window focus changes." You describe your app rules in ~/.config/keyd/app.conf using window class and title filters with Unix-style wildcards — for example, [chromium] with alt.] = macro(C-tab) gives Chromium its own tab-switching keys while every other app keeps the global behavior. A section like [gnome|*find*] matches any GNOME window whose title contains "find". Each section is, in the docs' words, "a set of application specific masks applied over the global rules defined in /etc/keyd/*.conf," and each binding uses the same syntax as the keyd bind command.

Display-server support is the honest caveat here: "At the moment X, Sway and Gnome are supported," with v2.5.0 adding KDE/plasma5 and GNOME 45/46, and v2.6.0 extending support to Cosmic and GNOME 49. The script needs keyd running and your user in the keyd group for socket access — and that membership carries a genuine security implication the Gentoo wiki states without sugar-coating: "When a user is made a member of the keyd group so as to be able to access /var/run/keyd.socket, it allows them to send keys system-wide. This creates a vulnerability that might be exploited by any malicious program within that user's environment." The upstream man page agrees, advising that "access to /var/run/keyd.socket should only be granted to trusted users and the group keyd should be regarded with the same reverence as wheel." Grant it to your own account, not to every user on a shared machine.

keyd vs kanata vs xremap — Which Remapper Fits You?

keyd is the minimalist Linux-native choice; kanata is the cross-platform maximalist; xremap sits between them as a Wayland-friendly Python-style alternative. A 2026 comparison by the keydo project's author (a competitor in this space, so read its framing accordingly) lays the three out cleanly, and the facts check out against keyd's own docs:

Choose keyd if you live on Linux and want the simplest config that still covers layers, overloads, and oneshot modifiers. Choose kanata if you need identical configs across Linux, macOS, and Windows and are comfortable with Lisp-style S-expressions — it adds primitives like tap-hold-release variants, chord groups, leader keys, and an optional TCP server for status bars. Consider xremap (or kanata) if your primary machine runs Wayland and you want per-application rules without a separate mapper script. Note that keydo is explicitly positioned as "Keyd, oxidised" — keyd's INI ergonomics reimplemented in Rust for portability. None of this is a rivalry to join; they are different answers to the same display-server wall keyd was built to climb over.

Setting Up keyd in Five Steps

Here is the complete beginner arc for this keyd tutorial, from zero to a working remap:

1. Install it. On Debian 13+, Ubuntu 25.04+, Arch, Fedora (COPR), openSUSE, Void, or Alpine, install the distro package; everywhere else, build from source with make && sudo make install and enable the service via sudo systemctl enable --now keyd.
2. Discover your key names. Run keyd monitor, press the keys you want to change, and note the names it reports. Stop the daemon first if you want the raw pre-remap events.
3. Write /etc/keyd/default.conf. Start with the [ids] wildcard and the capslock-overload plus oneshot-modifier starter config from the previous section.
4. Validate before you trust. Run keyd check on your file — as my captured session showed, a clean file prints "No errors found." and a broken one names the offending line. Then sudo keyd reload.
5. Iterate live. Use keyd monitor -t to tune tap-versus-hold timing, and remember the backspace+escape+enter panic sequence exists if anything goes sideways.

Sources

The following sources were all fetched and quoted on 2026-11-04. Star count and version details are snapshots as of that date.

• keyd README — "A key remapping daemon for linux." https://github.com/rvaiya/keyd — fetched 2026-11-04
• keyd man page (docs/keyd.scdoc) — https://raw.githubusercontent.com/rvaiya/keyd/master/docs/keyd.scdoc — fetched 2026-11-04
• keyd-application-mapper man page (docs/keyd-application-mapper.scdoc) — https://raw.githubusercontent.com/rvaiya/keyd/master/docs/keyd-application-mapper.scdoc — fetched 2026-11-04
• keyd CHANGELOG.md — https://raw.githubusercontent.com/rvaiya/keyd/master/docs/CHANGELOG.md — fetched 2026-11-04
• Gentoo wiki — "Keyd" — https://wiki.gentoo.org/wiki/Keyd/en — fetched 2026-11-04
• "Keyboard Remapping on Steroids: keyd vs. kanata vs. keydo" (dev.to, 2026-08-11) — https://dev.to/argenkiwi/keyboard-remapping-on-steroids-keyd-vs-kanata-vs-keydo-501e — fetched 2026-11-04
• Author's live session — keyd v2.6.0 built from source (master f564288, June 2026) on a Linux VM; keyd check validation of a valid and a broken config, captured 2026-11-04

Frequently Asked Questions

Is keyd really Linux-only?

Yes. keyd is built directly on Linux kernel input primitives — evdev to read your keyboard and uinput to inject the remapped events — and the project's own description is "A key remapping daemon for linux." It cannot run natively on macOS or Windows; if you need one config across operating systems, kanata is the cross-platform answer.

Will keyd work on Wayland?

Yes — that is its main selling point. Because keyd hooks the kernel's input subsystem below the display-server layer, its remaps behave identically on X11, Wayland compositors (Sway, Hyprland, GNOME), and pure virtual consoles. This is exactly what X11-bound tools like xmodmap cannot do, and the keyd Wayland story is the same one paragraph told twice: below the display server, there is nothing to be incompatible with.

Can a bad config lock me out of my keyboard?

It is possible to make the machine awkward to use with a bad config, but you have three safety nets: validate first with keyd check (shown working in this article), read errors in sudo journalctl -eu keyd, and if all else fails, the backspace+escape+enter panic sequence forces keyd to terminate.

How is keyd different from xmodmap?

xmodmap talks to the X11 server, so it only works inside X11 sessions and its changes can be lost when display settings reset. keyd works at the kernel input layer, so it is display-server-agnostic, lower-latency, and supports layers, tap/hold overloading, and oneshot modifiers that xmodmap never had.

Can different keyboards have different layouts?

Yes. Each config file's [ids] section lists which devices it applies to, so you can give your laptop keyboard, your external ergonomic board, and a macro pad each their own layer set on the same machine. The wildcard * applies a file to every keyboard keyd identifies.