keyd

Start and enable the keyd service

$ systemctl enable keyd --now

$ sudo keyd monitor

$ sudo keyd reload

$ keyd list-keys

$ sudo keyd bind "[pressed_key] = [output_key]"

keyd [OPTIONS]

--config
    Specify an alternative configuration file path to load instead of the default.

--fg
    Run keyd in the foreground; do not detach from the terminal. Useful for debugging purposes.

--loglevel
    Set the logging verbosity level for keyd. Common levels include debug, info, warn, and error.

--version
    Display keyd's version information and exit.

--help
    Display a brief help message outlining command-line options and exit.

keyd is a userspace daemon for Linux that provides powerful and flexible key remapping capabilities, including mouse buttons. It operates by creating virtual input devices using the uinput kernel module, allowing it to intercept and remap key events at a low level, independent of the display server. This makes it compatible with both X11 and Wayland environments, addressing a common limitation of older remapping tools. Users define custom key bindings, layers, and macros through a declarative configuration file, typically /etc/keyd/default.conf. keyd supports features like per-application keymaps, sticky layers, and complex macro sequences, enabling highly customized keyboard layouts and shortcuts far beyond standard system settings. It aims to offer a robust, simple, and performant alternative for advanced keyboard customization on Linux.

keyd requires the uinput kernel module to be loaded. It typically needs root privileges to start the daemon due to its interaction with input devices. It may conflict with other low-level keyboard remapping utilities or input device handlers if not configured carefully.

keyd operates based on a declarative configuration file, typically located at /etc/keyd/default.conf or ~/.config/keyd/default.conf. This file uses a simple, human-readable syntax to define key remappings, layers, macros, and application-specific rules. Users define layers (e.g., 'main', 'fn', 'media') and specify how keys behave within each layer or when certain applications are focused.

A significant advantage of keyd is its compatibility with both X11 and Wayland display servers. Unlike many older key remapping tools that are X11-specific, keyd operates at a lower level using the evdev and uinput kernel interfaces, allowing it to function seamlessly across modern Linux desktop environments without reliance on display server-specific APIs.

keyd is a relatively modern, open-source project developed to provide a robust and flexible solution for advanced keyboard remapping on Linux. It emerged to address limitations of older X11-specific tools, particularly the lack of Wayland compatibility and advanced features like key layering and application-specific rules. Its design emphasizes simplicity, performance, and cross-desktop environment functionality, quickly gaining traction among users seeking highly customized keyboard workflows.

keyd-query(1), xmodmap(1), setxkbmap(1), systemd(1)