keyd: The Only Linux Key Remapping Daemon You'll Ever Need

Why Are We Still Fighting With Key Remapping?

Let’s be honest — Linux key remapping has been a dumpster fire for years. I’ve watched countless developers waste hours wrestling with xmodmap and setxkbmap, only to have everything break when they switched to Wayland. And don’t even get me started on “hold-for-modifier, tap-for-something-else” patterns. The old tools simply can’t do it.

Last month, the keyd project hit 69 points with 33 comments on Hacker News. That’s a signal — people are still hurting from this problem. My own story is similar: I bought an HHKB last year, wanted to map right Ctrl to Backspace, tried every solution under the sun, and finally landed on keyd. Haven’t looked back since.

What Actually Is keyd?

Here’s the elevator pitch: keyd is a system-wide key remapping daemon that works directly at the Linux kernel input layer (evdev + uinput). No X11 dependency. No Wayland drama. It just works, regardless of your desktop environment — GNOME, KDE, i3, Sway, you name it.

Three killer features:

1. Truly system-wide — display server agnostic
2. Layers and key overloading — hold a key to switch layers, tap vs. hold for different actions
3. Performance — written in C, memory footprint under 2MB

Installation: Surprisingly Painless

I tested this on Arch, but the process is nearly identical on Ubuntu and Fedora.

# Arch Linux
yay -S keyd

# Or build from source
git clone https://github.com/rvaiya/keyd.git
cd keyd
make && sudo make install
sudo systemctl enable keyd --now

Verify it’s running:

sudo systemctl status keyd

If you see active (running), you’re halfway there.

Configuration: Where the Magic Happens

The config file lives at /etc/keyd/default.conf. Don’t let the syntax scare you — it’s surprisingly readable.

Scenario 1: Caps Lock → Ctrl

This is the classic Vim user request:

[ids]

[main]
capslock = leftcontrol

Two lines. Restart and you’re done:

sudo systemctl restart keyd

Scenario 2: Right Alt → Compose Key

[ids]

[main]
rightalt = compose

Scenario 3: Hold Ctrl for Super, Tap for Ctrl (Key Overloading)

This is where keyd absolutely shines:

[ids]

[main]
control = overload(control, super)

Tap it, and it’s a normal Ctrl. Hold it longer than 200ms, and it becomes Super. Emacs users love this — no more pinky gymnastics for that awkward Super key position.

Scenario 4: Custom Navigation Layer

Want to turn your right home row into arrow keys when holding a modifier?

[ids]

[main]
rightalt = layer(custom)

[custom]
j = left
k = down
l = right
i = up

This feels almost as good as QMK firmware on a programmable keyboard.

Real-World Pitfalls: What the Docs Don’t Tell You

1. Bluetooth Keyboard Discovery

My first Bluetooth keyboard was invisible to keyd. The fix? Use sudo keyd monitor to find the device ID:

$ sudo keyd monitor
/dev/input/event5: Apple Wireless Keyboard

Then specify it in the config:

[ids]
0001:0005

2. Conflicts With i3

If you’ve bound keys in both i3 config and keyd, they’ll fight. My rule of thumb: let keyd handle all key remapping, let i3 handle only window management. Clean separation, easier debugging.

3. SSH Sessions Don’t Inherit Mappings

This one trips people up. keyd only works on the local machine. SSH into a remote server? Your fancy key overloads don’t follow you. That’s by design — the remote server’s input chain is completely independent.

Performance Comparison: keyd vs. The Alternatives

The verdict is clear: keyd wins on features and modern compatibility. The only trade-off is an extra daemon, but at 1.5MB, who cares?

Advanced: Per-Device Configuration

Got multiple keyboards with different layouts? keyd supports per-device config files:

# /etc/keyd/apple-keyboard.conf
[ids]
05ac:0250

[main]
rightalt = compose

# /etc/keyd/hhkb.conf
[ids]
0853:0110

[main]
leftctrl = backspace
rightalt = layer(navigation)

The daemon matches devices automatically. This is miles better than udev hwdb, where you have to reload udev for every change.

Frequently Asked Questions

Q: What’s the difference between keyd and udev hwdb? A: udev hwdb works at the kernel level for basic key corrections, but it can’t do layers or overloading. keyd runs in userspace but uses uinput to simulate kernel input events, giving you the same compatibility with far richer functionality.

Q: My keyd config isn’t working. What’s wrong? A: Most likely a permissions issue. Make sure the keyd service is running and your user has access to /dev/uinput. Use sudo keyd monitor to debug.

Q: Will keyd affect my games? A: No. Games see standard key events after mapping. If you need raw behavior for a specific game, add a [games] exclusion section to your config.

Q: How does keyd compare to kmonad? A: kmonad is a solid project, but it’s written in Haskell with a more complex config syntax. keyd’s C implementation gives better performance and stability, and the config is far more intuitive.

Final Thoughts

keyd is hands-down the best Linux key remapping solution I’ve ever used. It solved my X11/Wayland migration anxiety and gave me a home for all those “non-standard” key habits I’ve accumulated over the years.

If you’re still using xmodmap, do yourself a favor and migrate. Wayland adoption isn’t slowing down, and your old tools will eventually fail you. keyd’s learning curve is maybe an hour or two, and the payoff is years of painless key management.

A few best practices to wrap up:

• Always use sudo keyd monitor for real-time debugging
• Split complex configurations into per-device files
• Restart the keyd service after upgrades — config format changes occasionally

Those 33 comments on Hacker News? A few people griped about sparse documentation. Fair point — the official docs are minimalist. But combine them with this guide, and you’ll cover 90% of use cases. The remaining 10%? Drop a comment. We’ll figure it out together.