Remap Caps Lock under Wayland

Caps Lock can be quite annoying, especially when entering passwords. It’s easy to activate unintentionally, not least because of its proximity to the home row. For that reason, many Linux users prefer to remap the key to something more functional.

Two alternatives are particularly useful. While the control key (Ctrl) is widely used by most applications, the necessary finger movement may over time cause chronic discomfort, a condition sometimes known as Emacs pinky. So Caps as Ctrl would be a good choice. Alternatively, remapping Caps to function as Escape key is particularly helpful for users of modal text editors like Neovim or Helix.

There are plenty of tutorials on this topic. For X11 I highly recommend Elijan Mastnak’s guide, which demonstrates how to give Caps Lock a dual function: tapping for Escape and longer pressing for Ctrl. Tutorials on how to implement the same behavior under Wayland, however, turned out to be surprisingly difficult to find – hence this article.

Static Key Remapping with XKB

Wayland recommends using the X keyboard extension (XKB) for keyboard configuration. For simple remappings – such as Caps Lock to Escape or Caps Lock to Ctrl – no additional tools are required.

Custom configurations can be stored under /etc/X11/xorg.conf.d/, e.g. in 90-custom-kbd.conf, where the number indicates its priority. The Arch Wiki provides an example of how to map Caps Lock to Escape:

Section "InputClass"
    Identifier "keyboard defaults"
    MatchIsKeyboard "on"

    Option "XKbOptions" "caps:escape"
EndSection

The Identifier is arbitrary and of no real significance for our concerns. The MatchIsKeyboard value specifies that the subsequent rule should apply to keyboards as device type.

The focus is of course on the last line of the section. The caps:escape option makes Caps Lock function as Escape. If you’d prefer to use it as Ctrl, substitute ctrl:nocaps instead. Backspace, Super (the “Windows key”), or Shift are equally possibly.

For an overview of all available options and their respective values, the following command can be helpful:

grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst

Dynamic Key Remapping with Keyd

I don’t think that dynamic remapping is possible with XKB, but keyd was created for this more specific purpose. While it’s not included in Fedora’s official repositories, contributor alternateved created a COPR repository to install keyd using DNF:

sudo dnf copr enable alternateved/keyd
sudo dnf install keyd

Settings for keyd are defined in /etc/keyd/default.conf:

[ids]

*

[main]

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

# Remaps the escape key to capslock
#esc = capslock

If you still want to retain a Caps Lock function, uncomment the last line.

Keyd runs as a background process managed by systemd:

systemctl start keyd
systemctl enable keyd

The first command starts the daemon for the current session. The second ensures that the process starts automatically on boot.