Remap Keys in i3

13 July 2023

Here's how to remap a keyboard key in i3.

Controlled by X

X Window System is a window system for Unix. Aka Xorg. Aka X. Aka X11, because v11 is its latest stable release. This is the default display server for Ubuntu/derivatives.

Keyboard mapping is controlled by X, not i3 per se. i3 is the window manager on top of X.

Map the Key with xmodmap

There's a pre-install utility for mapping keys called xmodmap. it takes an expression that describes the mapping.

To remap the caps lock key to escape, run:

xmodmap -e "keycode 66 = Escape NoSymbol Escape"
  • -e is the expression argument for the mapping.
  • 66 is the keycode for the capslock key.
  • The 3 key symbols after the = (here, Escape) represent the action that will be activated when the (66) key is pressed in 3 configurations.

Find the Keycode

To discover the keycode you want to map, use another utility, xev. Running this will open a window, allow you press the key that you're wondering about, capture that press and read the keycode in the output.

When I press caps lock, I get this output:

KeyRelease event, serial 34, synthetic NO, window 0x5c00001,
    root 0x79c, subw 0x0, time 34391409, (113,429), root:(1557,449),
    state 0x0, keycode 66 (keysym 0xff1b, Escape), same_screen YES,
    XKeysymToKeycode returns keycode: 9
    XLookupString gives 1 bytes: (1b) "
FilterEvent returns: False

Keycode (not order) 66.

Find the Key Symbols

To discover what the mappings currently are and the key symbol names, use xmodmap -pke. This will output all expressions as currently mapped.

Place Symbols in the Right Order

To determine the meaning of the order of the key symbols, we read the manual (man xmodmap):

The list of keysyms is assigned to the indicated keycode (which may be specified in decimal, hex or octal and can be determined by running the xev program). Up to eight keysyms may be attached to a key, however the last four are not used in any major X server implementation. The first keysym is used when no modifier key is pressed in conjunction with this key, the second with Shift, the third when the Mode_switch key is used with this key and the fourth when both the Mode_switch and Shift keys are used.

Apparently mode_switch is an old key on old keyboards, predating xkb, how X handles keyboard coding now. It's a legacy feature artifact.

With keycode, symbols and order, you're set to create your own mapping.

Always set on i3 Startup

And now for i3. If you want to have this mapping set every time i3 starts up, you can set it in your ~/.config/i3/config file:

exec_always --no-startup-id xmodmap -e "keycode 66 = Escape NoSymbol Escape"