---
name: "evremap"
section: "1"
platform: "linux"
package: "evremap"
version: "0.0~git20240617.cc618e8-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/evremap"
---

# evremap(1)

keyboard input remapper for Linux/Wayland systems

## NAME

evremap - keyboard input remapper for Linux/Wayland systems

## DESCRIPTION

evremap works by grabbing exclusive access to an input device and maintaining a model of the keys that are pressed. It then applies your remapping configuration to produce the effective set of pressed keys and emits appropriate changes to a virtual output device.

Because evremap targets the evdev layer of libinput, its remapping is effective system-wide: in Wayland, X11 and the linux console.

[evtest(1)](/evtest/1.md) can be used to identify keycodes of an input device.

### USAGE:

-

  **evremap remap** *config-file* --delay \<delay\>

- **evremap list-devices**

  - **evremap list-keys**

  - **evremap debug-events**

  ### FLAGS:

- **-d**, **--delay \<delay\>**

  Startup delay in second

- **-h**, **--help**

  Prints help information

- **-V**, **--version**

  Prints version information

### SUBCOMMANDS:

- help

  Prints this message or the help of the given subcommand(s)

- list-devices

  Rather than running the remapper, list currently available devices. This is helpful to check their names when setting up the initial configuration

- list-keys

  Show a list of possible KEY\_XXX values

- debug-events

  Listen to events and print them out to facilitate learning which keys/buttons have which labels for your device(s)

- remap

  Load a remapper config and run the remapper. This usually requires running as root to obtain exclusive access to the input devices

## FILE

- */etc/evremap.conf*

  Mapping configuration file

## Sample Configuration

```
# The name of the device to remap.
# Run `sudo evremap list-devices` to see the devices available
# on your system.
device_name = "AT Translated Set 2 keyboard"
# If you have multiple devices with the same name, you can optionally
# specify the `phys` value that is printed by the `list-devices` subcommand
# phys = "usb-0000:07:00.3-2.1.1/input0"
# Configure CAPSLOCK as a Dual Role key.
# Holding it produces LEFTCTRL, but tapping it
# will produce ESC.
# Both `tap` and `hold` can expand to multiple output keys.
[[dual_role]]
input = "KEY_CAPSLOCK"
hold = ["KEY_LEFTCTRL"]
tap = ["KEY_ESC"]
# This config snippet is useful if your keyboard has an arrow
# cluster, but doesn't have page up, page down, home or end
# keys.  Here we're configuring ALT+arrow to map to those functions.
[[remap]]
input = ["KEY_LEFTALT", "KEY_UP"]
output = ["KEY_PAGEUP"]
[[remap]]
input = ["KEY_LEFTALT", "KEY_DOWN"]
output = ["KEY_PAGEDOWN"]
[[remap]]
input = ["KEY_LEFTALT", "KEY_LEFT"]
output = ["KEY_HOME"]
[[remap]]
input = ["KEY_LEFTALT", "KEY_RIGHT"]
output = ["KEY_END"]
# When applying remapping configuration, ordering is important:
# Dual Role entries are always processed first Remap entries are applied in
# the order that they appear in your configuration file
# Here's an example where ordering is important: on the PixelBook Go keyboard, the
# function key row has alternate functions on the keycaps. It is natural to want
# the mute button to mute by default, but to emit the F8 key when holding alt. We
# can express that with the following configuration:
[[remap]]
input = ["KEY_LEFTALT", "KEY_F8"]
# When our `input` is matched, our list of `output` is prevented from
# matching as the `input` of subsequent rules.
output = ["KEY_F8"]
[[remap]]
input = ["KEY_F8"]
output = ["KEY_MUTE"]
```

## SEE ALSO

[**evtest**(1)](/evtest/1.md)

## AUTHOR

This man page was written by Yifei Zhan \<yifei@zhan.science\> using README.md from https://github.com/wez/evremap\
 This program was written by Wez Furlong