xmodmap

Swap and on the pointer

$ xmodmap -e 'pointer = 3 2 1'

$ xmodmap -e 'keycode [keycode] = [keyname]'

$ xmodmap -e 'keycode [keycode] ='

$ xmodmap [path/to/file]

xmodmap [options] [filename]

-display display
    Specifies the X server to connect to. If not specified, the value of the DISPLAY environment variable is used.

-verbose
    Prints a log of the actions taken by xmodmap, showing what expressions are parsed and what changes are applied.

-quiet
    Suppresses output. This is the default behavior when no other output-generating options are specified.

-noconnect
    Prevents xmodmap from connecting to the X server. Useful for checking the syntax of expressions in a file without applying changes.

-grammar
    Prints a brief usage message about the expression grammar recognized by xmodmap.

-pk or -pke
    Prints the current X keyboard keymap table. -pke includes empty keycode entries.

-pm
    Prints the current X keyboard modifier map, showing which keycodes are bound to which modifier (Shift, Lock, Control, Mod1-Mod5).

-pbt
    Prints the current pointer button map, showing the mapping of physical mouse buttons to logical button numbers.

-e expression
    Executes a single xmodmap expression directly from the command line. Multiple -e options can be used.

-s
    Causes xmodmap to ignore any file specified on the command line and instead attempt to load an initial keymap from ~/.Xmodmap (or a system-wide default such as /etc/X11/Xmodmap).

-
    Reads expressions from standard input (stdin) instead of a file.

filename
    Specifies a file containing xmodmap expressions to be executed. If not specified, and -s is not used, no actions are taken unless -e is used.

xmodmap is a utility for modifying the keyboard modifier map and keymap table, as well as the pointer button map in the X Window System. It allows users to reassign keys, swap functions of modifier keys (like Caps Lock and Control), and adjust mouse button mappings. The command works by interpreting a list of expressions that specify changes to the X server's keymap. These changes are applied directly to the current X display.

Common uses include remapping specific keys to different symbols (keysyms), adding or removing keys from modifier sets (e.g., making a key act as a Shift or Alt modifier), or changing the order of mouse buttons. While powerful for direct manipulation of the X server's keymap, xmodmap is a lower-level tool. For complex international layouts or modern systems, setxkbmap (which uses the XKB extension) is often preferred, as it provides a more robust and feature-rich way to manage keyboard layouts.

Changes made with xmodmap are session-specific and not persistent across reboots unless configured to load automatically at startup (e.g., via .xinitrc, desktop environment startup scripts, or an .Xmodmap file).

xmodmap operates at a lower level than the X Keyboard Extension (XKB), which is managed by tools like setxkbmap. Using xmodmap can sometimes interfere with or be overridden by XKB configurations, especially in modern desktop environments that rely heavily on XKB for keyboard layout management. It's generally recommended to use setxkbmap for complex keyboard layouts or when persistent changes are desired across different XKB configurations.

xmodmap accepts various types of expressions for remapping keys and modifiers. Common forms include:
keycode NUMBER = KEYSYM1 [KEYSYM2 ...]: Assigns keysyms to a physical keycode.
keysym KEYSYM_NAME = KEYSYM1 [KEYSYM2 ...]: Finds a keycode associated with a keysym and reassigns its keysyms.
add MODIFIER_NAME = KEYSYM1 [KEYSYM2 ...]: Adds keysyms to a modifier set.
remove MODIFIER_NAME = KEYSYM1 [KEYSYM2 ...]: Removes keysyms from a modifier set.
clear MODIFIER_NAME: Removes all keys from a modifier set.
pointer = BUTTON1 BUTTON2 BUTTON3 ...: Remaps mouse buttons.

To make xmodmap changes persistent across X sessions, expressions are typically placed in a file named .Xmodmap in the user's home directory. This file is then usually loaded automatically by the X server during startup or by a session manager (e.g., through .xinitrc or a desktop environment's autostart mechanism) using the command xmodmap ~/.Xmodmap. The -s option can also trigger this loading mechanism.

Understanding the difference between keycodes and keysyms is crucial for effective use of xmodmap. A keycode is a hardware-generated number that identifies a physical key on the keyboard. A keysym (key symbol) is a symbolic name for the meaning of a key, such as Shift, a, Return, or Caps_Lock. xmodmap works by mapping keycodes to a list of keysyms, where different positions in the list correspond to various shift states (e.g., normal, Shift, Mod1+Shift, etc.).

xmodmap is one of the foundational utilities of the X Window System, developed early in its history to provide a direct method for users to customize their input device mappings. For many years, it was the primary tool for remapping keys and adjusting pointer behavior. While it remains functional and useful for simple, ad-hoc changes, its role for comprehensive keyboard layout management has largely been superseded by the X Keyboard Extension (XKB), which offers a more powerful and flexible framework for handling diverse keyboard layouts and variations. Despite the rise of XKB, xmodmap still holds a place for direct keycode-to-keysym mappings and fine-tuning specific modifier behaviors.

setxkbmap(1), xev(1), xset(1), xkeycaps(1)