xmodmap - ArchWiki

# xmodmap

Related articles

- Xorg
- Extra keyboard keys
- Extra keyboard keys in Xorg
- Extra keyboard keys in console
- Xbindkeys

xmodmap is a utility for modifying keymaps and pointer button mappings in Xorg.

xmodmap is not directly related to X KeyBoard extension (XKB), as it uses different (pre-XKB) ideas on how keycodes are processed within X. Generally, it is only recommended for the simplest tasks. See X KeyBoard extension for advanced layout configuration.

## Introduction

There are two types of keyboard values in Xorg: keycodes and keysyms.

keycode
  The keycode is the numeric representation received by the kernel when a key or a mouse button is pressed.
keysym
  The keysym is the value assigned to the keycode. For example, pressing `A` generates the `keycode 73`, which is mapped to the `keysym 0×61`, which matches `A` in the ASCII table.
  The keysyms are managed by Xorg in a table of keycodes defining the keycode-keysym relations, which is called the keymap table. This can be shown by running `xmodmap`.

## Installation

xmodmap can be installed through the xorg-xmodmap package from the official repositories.

Optionally, install xkeycaps, which is a graphical front-end to xmodmap.

## Keymap table

Print the current keymap table formatted into expressions:

    $ xmodmap -pke

    [...]
    keycode  57 = n N
    [...]

Each keycode is followed by the keysym it is mapped to. The above example indicates that the keycode `57` is mapped to the lowercase `n`, while the uppercase `N` is mapped to keycode `57` plus `Shift`.

Each keysym column in the table corresponds to a particular combination of modifier keys:

1. `Key`
2. `Shift+Key`
3. `mode_switch+Key`
4. `mode_switch+Shift+Key`
5. `AltGr+Key`
6. `AltGr+Shift+Key`

Not all keysyms have to be set, but to assign only a latter keysym, use the `NoSymbol` value.

To see which keycode corresponds to a key, see Extra keyboard keys#In Xorg for details on the xev utility.

Tip: There are predefined descriptive keysyms for multimedia keys, e.g. `XF86AudioMute` or `XF86Mail`. These keysyms can be found in `/usr/include/X11/XF86keysym.h`. Many multimedia programs are designed to work with these keysyms out-of-the-box, without the need to configure any third-party application.

## Custom table

To create a key map (i.e. `~/.Xmodmap`):

    $ xmodmap -pke > ~/.Xmodmap

To test the changes:

    $ xmodmap ~/.Xmodmap

### Activating the custom table

With GDM, XDM, KDM or LightDM there is no need to source `~/.Xmodmap`. For startx, use:

    ~/.xinitrc

    if [ -s ~/.Xmodmap ]; then
        xmodmap ~/.Xmodmap
    fi

Alternatively, edit the global startup script `/etc/X11/xinit/xinitrc`.

### Test changes

To make temporary changes:

    $ xmodmap -e "keycode  46 = l L l L lstroke Lstroke lstroke"
    $ xmodmap -e "keysym a = e E"

## Modifier keys

xmodmap can also be used to override modifier keys, e.g. to swap `Control` and `Super` (the Windows keys).

Before assignment the modifier keys need to be empty. `!` is a comment, so only the modifiers `Control` and `Mod4` get cleared in the following example. Then the keysyms `Control_L`, `Control_R`, `Super_L` and `Super_R` are assigned to the opposite modifier. Assigning both left and right to the same modifier means that both keys are treated the same way.

    ~/.Xmodmap

    [...]
    !clear Shift
    !clear Lock
    clear Control
    !clear Mod1
    !clear Mod2
    !clear Mod3
    clear Mod4
    !clear Mod5
    !add Shift   = Shift_L Shift_R
    !add Lock    = Caps_Lock
    add Control = Super_L Super_R
    !add Mod1    = Alt_L Alt_R
    !add Mod2    = Mode_switch
    !add Mod3    =
    add Mod4    = Control_L Control_R
    !add Mod5    =

Note: The example assumes that the `Control_L` and `Control_R` keysyms were assigned to the `Control` modifier, and `Super_L` and `Super_R` keysyms to the `Mod4` modifier. If you get the following error message `X Error of failed request: BadValue (integer parameter out of range for operation)`, you will need to adapt accordingly. Running `xmodmap` produces a list of modifiers and keys that are assigned to them.

## Reverse Scrolling

The natural scrolling feature available in OS X Lion (mimicking smartphone or tablet scrolling) can be replicated with xmodmap. Since the synaptics driver uses the buttons 4/5/6/7 for up/down/left/right scrolling, you simply need to swap the order of how the buttons are declared in `~/.Xmodmap`:

    ~/.Xmodmap

    pointer = 1 2 3 5 4 7 6 8 9 10 11 12

Then update xmodmap:

    $ xmodmap ~/.Xmodmap

## Templates

### Spanish

    ~/.Xmodmap

    keycode  24 = a A aacute Aacute ae AE ae
    keycode  26 = e E eacute Eacute EuroSign cent EuroSign
    keycode  30 = u U uacute Uacute downarrow uparrow downarrow
    keycode  31 = i I iacute Iacute rightarrow idotless rightarrow
    keycode  32 = o O oacute Oacute oslash Oslash oslash
    keycode  57 = n N ntilde Ntilde n N n
    keycode  58 = comma question comma questiondown dead_acute dead_doubleacute dead_acute
    keycode  61 = exclam section exclamdown section dead_belowdot dead_abovedot dead_belowdot
    !Maps the Mode key to the Alt key
    keycode 64 = Mode_switch

### Turn CapsLock into Control, and LeftControl into Hyper

Laptop users may prefer having `CapsLock` as `Control`. The `Left Hyper` key can be used as a modifier.

    ~/.Xmodmap

    clear      lock
    clear   control
    clear      mod1
    clear      mod2
    clear      mod3
    clear      mod4
    clear      mod5
    keycode      37 = Hyper_L
    keycode      66 = Control_L
    add     control = Control_L Control_R
    add        mod1 = Alt_L Alt_R Meta_L
    add        mod2 = Num_Lock
    add        mod3 = Hyper_L
    add        mod4 = Super_L Super_R
    add        mod5 = Mode_switch ISO_Level3_Shift

### Switch every number key N with Shift-N and vice-versa, for Croatian layout

Should work fine for layouts similar to Croatian as well.

    ~/.Xmodmap

    keycode 10 = exclam 1 1 exclam asciitilde dead_tilde asciitilde
    keycode 11 = quotedbl 2 2 quotedbl dead_caron caron dead_caron
    keycode 12 = numbersign 3 3 numbersign asciicircum dead_circumflex asciicircum
    keycode 13 = dollar 4 4 dollar dead_breve breve dead_breve
    keycode 14 = percent 5 5 percent degree dead_abovering degree
    keycode 15 = ampersand 6 6 ampersand dead_ogonek ogonek dead_ogonek
    keycode 16 = slash 7 7 slash grave dead_grave grave
    keycode 17 = parenleft 8 8 parenleft dead_abovedot abovedot dead_abovedot
    keycode 18 = parenright 9 9 parenright dead_acute apostrophe dead_acute
    keycode 19 = equal 0 0 equal dead_doubleacute doubleacute dead_doubleacute

## See also

- Current man page at X.Org Foundation
- Multimediakeys with .Xmodmap HOWTO by Christian Weiske
- Mapping unsupported keys with xmodmap by Pascal Bleser
- List of Keysyms Recognised by Xmodmap on LinuxQuestions

Categories:

- Keyboards
- X Server