xremap

:keyboard:

xremap is a key remapper for Linux. Unlike xmodmap, it supports app-specific remapping and Wayland.

Table of contents

• Concept
• Features
• Installation
• Usage
• Configuration
• Commandline arguments
• Maintainers
• License

See also: Documentation section

Concept

• Fast - Xremap is written in Rust, which is faster than JIT-less interpreters like Python.

• Cross-platform - Xremap uses evdev and uinput, which works whether you use X11 or Wayland.

• Language-agnostic - The config is JSON-compatible. Generate it from any language, e.g. Ruby, Python.

Features

• Remap any keys, e.g. Ctrl or CapsLock.
• Remap any key combination to another, even to a key sequence.
• Remap a key sequence as well. You could do something like Emacs's C-x C-c.
• Remap a key to two different keys depending on whether it's pressed alone or held.
• Application-specific remapping. Even if it's not supported by your application, xremap can.
• Device-specific remapping.
• Automatically remap newly connected devices by starting xremap with --watch.
• Support Emacs-like key remapping, including the mark mode.
• Trigger commands on key press/release events.
• Use a non-modifier key as a virtual modifier key.

Installation

Xremap comes as a full variant (since v0.15.13), which includes support for all desktops and window managers. Otherwise a specific variant can be chosen, with support for just one each.

After installation there're also manual instructions below.

The community has a task to discuss what the meaning of xremap should be in distro packages and on the release page. Should it mean xremap-minimal with no desktop support or should it mean xremap-full with all supported desktops and auto selection.

Packages

• If you are using Arch there're packages in AUR.
• If you are using NixOS, xremap provides a flake.
• If you are using Fedora, xremap can be installed via a community Copr.
• If you are using Gentoo Linux, xremap can be installed via ::guru overlay.

Release page

Otherwise xremap is available on the Download page for all™ linux distros. There're generally no extra requirements than the single binary.

From source

Instructions for GitHub and crates.io Instructions for FreeBSD

Usage

If something isn't working take a look at the troubleshooting section

Run with sudo

First perform these installation instructions: Running xremap with sudo

sudo xremap config.yml

Run without sudo

First perform these installation instructions: Running xremap without sudo

xremap config.yml

Configuration

Your config.yml should look like this:

modmap:
  - remap:
      CapsLock: Esc
keymap:
  - remap:
      Ctrl-P: Up
      Ctrl-N: Down

A configuration file has 3 parts: modmap, keymap and Configuration options. modmap and keymap are described below.

There are examples of a more realistic config and an emacs inspired config.

Key names

All possible keys are listed here. You can skip KEY_ and the names are case-insensitive. So KEY_CAPSLOCK, CAPSLOCK, and CapsLock are the same thing.

The keys are described in more detail in Key names. Some custom aliases like Shift_R and Control_L also exists.

In case you don't know the name of a key, you can find out by enabling debug output:

RUST_LOG=debug xremap config.yml

Then press the key you want to know the name of. Remember sudo if that's needed.

Examples

In the examples, note whether they use modmap or keymap.

Exchange Capslock and Esc

modmap:
  - remap:
      Capslock: Esc
      Esc: Capslock

The remapping will also be used in keymap, e.g. definitions with Esc in keymap will match the physical Capslock key. This is because the output of modmap goes through keymap.

Disable a key

modmap:
  - remap:
      F9: []

The meaning of the config is: F9 remaps to an empty list of keys.

Remap a key combo to another key combo

keymap:
  - remap:
      Ctrl-P: Up
      Ctrl-N: Down

This configuration allows extra modfiers to be pressed. This means if Ctrl, Shift and P are pressed, it will remap to Shift-Up, allowing to select text up and down.

Remap an exact key combo

To make the remapping Ctrl-P: Up only match with the exact modifiers pressed:

keymap:
  - exact_match: true
    remap:
      Ctrl-P: Up
      Ctrl-N: Down

This means if Ctrl, Shift and P are pressed, it won't match. The keys are passed through as is, and the combo Ctrl-Shift-P does the same thing it does without xremap running.

Different remap for left and right modifiers

keymap:
  - remap:
      Ctrl_R-C: End
      Ctrl_R-X: Home

Pressing right Ctrl and C remaps to End. This leaves the normal remapping of Ctrl-C using left Ctrl to copy text.

Reload xremap with a key combo

keymap:
  - remap:
      f9: { action: reload }

List of all actions.

modmap

modmap is for key-to-key remapping like xmodmap. Note that remapping a key to a modifier key, e.g. CapsLock to Control_L, is supported only in modmap since keymap handles modifier keys differently.

…

keymap

keymap is for remapping a sequence of key combinations to another sequence of key combinations or other actions. Key actions in keymap will generally press and release keys right away when the last key in the trigger combination is pressed.

…

What to use for modifiers, the MOD- part, is described in Key names.

exact_match

exact_match controls how modifiers are matched. A remapping, where modifiers match exactly will always be used. But when such a remapping doesn't exist, the default is to try an inexact match, this can be disabled with exact_match=true.

Example of inexact match: Given a mapping of Ctrl-n: down, and you pressed Ctrl-Shift-n, it will automatically be remapped to Shift-down. With exact matching, you would have to define a mapping for Ctrl-Shift-n.

application

application can be used for both modmap and keymap, which allows you to specify application-specific remapping.

keymap:
  - application:
      not: firefox
      #not: [firefox, ...]
      #only: firefox
      #only: [firefox, ...]
    remap:
      capslock: KEY_A

The application name can be specified as a normal string to exactly match the name, or a regex surrounded by / like /application/.

To check the application names, you can use the following command:

xremap --list-windows

It was added in v0.15.5. See methods prior to that. It doesn't work on GNOME Wayland or KDE Wayland, though. But there it's possible to do:

GNOME Wayland

Use the following command or check windows' WMClass by pressing Alt+F2 and running lg command in LookingGlass:

busctl --user call org.gnome.Shell /com/k0kubun/Xremap com.k0kubun.Xremap WMClasses

KDE-Plasma Wayland

Xremap prints the active window to the console. However, it will only start printing, once a mapping has been triggered that uses an application filter. So you have to create a mapping with a filter using a dummy application name and trigger it. Then each time you switch to a new window xremap will print its caption and class in the following style: active window: caption: '<caption>', class: '<class>' The class property should be used for application matching, while the caption property should be used for window matching.

If you use a systemd-daemon to manage xremap, the prints will be visible in the system-logs (Can be opened with journalctl -f)

application-specific key overrides

Sometimes you want to define a generic key map that is available in all applications, but give specific keys in that map their own definition in specific applications. You can do this by putting the generic map at the bottom of the config, after any specific overrides, as follows.

# Emacs-style word-forward and word-back
keymap:
  - name: override to make libreoffice-writer go to end of word but before final space like emacs
    application:
      only: libreoffice-writter
    remap:
      Alt-f: [right, C-right, left]
  - name: generic for all apps
    remap:
      Alt-f: C-right
      Alt-b: C-left

Note how Alt-f and Alt-b work in all apps, but the definition of Alt-f is slightly different in LibreOffice Writer. When that app is active, the first definition overrides the second definition; but for any other app, only the second definition is found. This is because xremap uses the first matching definition that it finds.

device

Much like application, you may specify {keymap,modmap}.device.{not,only} in your configuration for device-specific remapping. Consistent with the global --device flag, device-matching strings may be any of:

• The full path of the device (e.g. /dev/input/event0)
• The filename of the device (e.g. event0)
• The device name
• A substring of the device name
• The vendor and/or product id (e.g. ids:0x3f0:0x24)

To determine the names and paths of your devices, examine xremap's log output at startup. To get further info run: xremap --list-devices or even xremap --device-details.

keymap:
  - device:
      not: "/dev/input/event0"
      # not: "/dev/input/by-id/Cool_Device" # Symlink to device. Since v0.14.8
      # not: [event0, event1]
      # only: 'Some Cool Device Name'
      # only: ['Cool Device', 'Another Device']
      # only: [ids:0x3f0:0x24]
    remap:
      W: UP

Unlike for application, regexs are not supported for device.

If both not and only is specified, then only is used for matching, and not has no effect.

Vendor and product ids must be given in hexadecimal, with or without '0x' prefix. It's possible to only match on vendor id with: ids:0x3f0:0, and only on product id with ids:0:0x24.

mode

You can assign mode(s) to keymap and/or remap which effectively turns them on or off when you set the mode.

…

Commandline arguments

Usage for xremap is shown by running the following command:

xremap --help

The result is shown here:

…

Device/ignore

The arguments taken by --device and --ignore are described here. When using --device, only the devices you specify will be used. To select more than one device separate them by , or use --device for each:

xremap --device "first device,second device" config.yml

or:

xremap --device "first device" --device "second device" config.yml

Maintainers

• @k0kubun
• @N4tus (KDE client)
• @jixiuf (wlroots client)
• @saurabhsharan (Niri client)
• @hpccc53 (COSMIC, Pantheon client)

Releasing

First