Change X Keyboard and Mouse Mappings Safely with xmodmap

Swap the wrong key with xmodmap and you can lock yourself out of typing "xmodmap" to undo it, which is why the save-first habit in this guide matters. You will inspect the current mappings, try a reversible pointer change, and save a keyboard mapping you can restore later. The examples use xmodmap 1.0.11 from Debian package x11-xserver-utils version 7.7+10build2.

Allow about fifteen minutes. You need an X session with a working DISPLAY, a shell, and permission to connect to that display. These commands change the mappings for the current X display only: they do not touch the Linux console, a Wayland compositor, or your desktop environment's persistent keyboard settings.

1. Check the installed command and display

Confirm which executable and package version you are actually using first. This is read-only:

$ command -v xmodmap
/usr/bin/xmodmap
$ xmodmap -version
xmodmap 1.0.11
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xserver-utils
x11-xserver-utils 7.7+10build2

Check the display before you attempt a mapping operation:

$ printf 'DISPLAY=%s\n' "${DISPLAY:-unset}"
DISPLAY=:0

Your value will differ. unset means xmodmap normally cannot connect to an X server at all. A named display that still fails access means: use the shell belonging to that graphical session and check its X authorisation. Never guess a display number.

2. Save a rollback copy

Print the current keymap as xmodmap expressions with -pke, then redirect that output to a file in your home directory:

$ xmodmap -pke > "$HOME/xmodmap-before"
$ test -s "$HOME/xmodmap-before" && printf '%s\n' 'saved keymap'
saved keymap

This file is a snapshot of this keyboard map, not a universal config for another keyboard. Keep it private if the layout is sensitive. It does not save the pointer map though, so record that separately if you plan to change buttons:

$ xmodmap -pp
There are 3 pointer buttons defined.
    Physical        Button
     Button          1
     Button          2
     Button          3

The exact output is host-specific. For a complete pointer rollback, copy the numbered mapping shown here and turn it into a pointer = ... expression later.

3. Inspect without changing anything

The default mode prints the modifier map. Reach for the other print modes when you need a different view:

$ xmodmap -pm
shift       Shift_L (0x32),  Shift_R (0x3e)
lock        Caps_Lock (0x42)
control     Control_L (0x25),  Control_R (0x69)
$ xmodmap -pk | sed -n '1,12p'
There are 4 KeySyms per KeyCode; KeyCodes start at 8
     8     0x0000 (NoSymbol)  0x0000 (NoSymbol)  0x0000 (NoSymbol)  0x0000 (NoSymbol)
     9     0xff1b (Escape)    0x0000 (NoSymbol)  0x0000 (NoSymbol)  0x0000 (NoSymbol)
     10    0x0031 (1)         0x0021 (exclam)    0x0000 (NoSymbol)  0x0000 (NoSymbol)

• -pm shows modifier membership.
• -pk shows keycodes and keysyms.
• -pke prints the same keysym data in a form you can feed straight back to xmodmap.

Output depends on the server and keyboard, and a key appearing in the keymap does not by itself mean it belongs to a modifier.

4. Test a pointer mapping with dry run

Use -n to show what an expression would do without actually changing anything. For a three-button mouse, this tests a left-handed order:

$ xmodmap -n -e 'pointer = 3 2 1'
pointer = 3 2 1

The pointer list starts with physical button 1, and a zero disables events from that button entirely. This dry run is a parser and operation preview; it does not prove the live pointer will actually feel right on your device.

$ xmodmap -e 'pointer = 3 2 1'
$ xmodmap -pp
There are 3 pointer buttons defined.

Test the buttons before changing anything else. To undo this exact example, apply xmodmap -e 'pointer = 1 2 3', or use the order you recorded from the earlier -pp output. That inverse is not automatically correct for a mouse with a different number of buttons.

5. Change a key without leaving a modifier behind

A keysym assignment changes the keymap, but a modifier map is a separate thing entirely. To swap Caps Lock and left Control, remove both old modifier memberships, change the keysyms, then add the new memberships:

$ xmodmap -n -e 'remove Lock = Caps_Lock' \
    -e 'remove Control = Control_L' \
    -e 'keysym Control_L = Caps_Lock' \
    -e 'keysym Caps_Lock = Control_L' \
    -e 'add Lock = Caps_Lock' \
    -e 'add Control = Control_L'
remove Lock = Caps_Lock
remove Control = Control_L
keysym Control_L = Caps_Lock
keysym Caps_Lock = Control_L
add Lock = Caps_Lock
add Control = Control_L

Read the preview carefully. The command parses all its -e expressions before executing any of them, which is exactly why a swap like this can refer to the old names naturally. The manual also warns that each keycode change fires a MappingNotify event, so batching related expressions avoids unnecessary client churn.

Preview looks right? Drop -n, run the same command, then check both views:

$ xmodmap -pm
$ xmodmap -pk | grep -E 'Caps_Lock|Control_L'

The grep result is a quick inspection, not a fixed expected line: keycodes and unrelated columns vary by keyboard.

6. Restore the saved keyboard map

Confused by the result? Restore the snapshot from step 2:

$ xmodmap "$HOME/xmodmap-before"
$ xmodmap -pke > /tmp/xmodmap-after
$ cmp -s "$HOME/xmodmap-before" /tmp/xmodmap-after \
    && printf '%s\n' 'keyboard map restored'
keyboard map restored

The comparison can differ in harmless formatting on some servers, so test the keys physically too. If xmodmap reports it cannot open the display, do not edit the saved file to compensate: reconnect to the correct X session first. Remove the temporary comparison file once you are done with it.

For a persistent login setup, put only tested expressions in the session mechanism your desktop environment provides. Do not blindly run a full -pke snapshot at every login: that snapshot describes one keyboard and can overwrite changes made by the desktop or another input tool.