Jump to content

# xmodmap

From ArchWiki

Related articles

- Xorg
- Xorg/Keyboard_configuration
- Keyboard input
- Extra keyboard keys in console
- Xbindkeys

This article or section needs expansion.

Reason: Why is xmodmap only recommended for the simplest tasks? (Discuss in Talk:Xmodmap)

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.

Note

- xmodmap settings are reset by setxkbmap, which not only alters the alphanumeric keys to the values given in the map, but also resets all other keys to the startup default (see LQWiki:Configuring keyboards).
- Due to a limitation of Xorg, xmodmap settings are not applied to hotplugged devices automatically. If a keyboard is added to a system after a custom table has been applied, the custom table will have to be applied again. [1]

## 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 38`, 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.

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. `ISO_Level3_Shift+Key`
6. `ISO_Level3_Shift+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 Keyboard input#Identifying keycodes in Xorg for details on the xev utility which will output relevant keycode/keysym information about a key when you press it.

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.

Note that xmodmap is influenced by xkbd settings, so all eight keysym are available for the US(intl) xkbd layout but not for the default US (it is missing the ralt_switch symbol defined in level3). To have all 8 keysyms available you should configure the (intl) variant of the keyboard. Using US layout as an example, `$ setxkbmap -layout 'us(intl)'` before calling xmodmap to test your changes in the current X session. To permanently make this change, edit the xorg configuration or your .xprofile or .xinitrc file. See Xorg/Keyboard configuration#Setting keyboard layout for a full explanation.

## 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 or LightDM there is no need to source `~/.Xmodmap`. For startx, use:

    ~/.xinitrc

    [[ -f ~/.Xmodmap ]] && xmodmap ~/.Xmodmap

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 key).

Print the current modifier table verbosely (full sample):

    $ xmodmap -pm

    xmodmap:  up to 4 keys per modifier, (keycodes in parentheses):

    shift       Shift_L (0x32),  Shift_R (0x3e)
    lock        Caps_Lock (0x42)
    control     Control_L (0x25),  Control_R (0x69)
    mod1        Alt_L (0x40),  Meta_L (0xcd)
    mod2        Num_Lock (0x94)
    mod3
    mod4        Super_R (0x86),  Super_L (0xce),  Hyper_L (0xcf)
    mod5        ISO_Level3_Shift (0x5c),  ISO_Level3_Shift (0x6c),  Mode_switch (0x85),  Mode_switch (0xcb)

### Finding the keysym column modifier keys

This article or section is a candidate for merging with #Keymap table.

Notes: The point of this section does not seem to be finding anything. The meaning of the modifier keys should be explained in #Keymap table where they are mentioned first. (Discuss in Talk:Xmodmap)

ISO_Level3_Shift
  The AltGr key on non-US keyboards calls modifier ISO_Level3_Shift. (On US keyboards, the right-alt `Alt_R` has the same function as the left-alt `Alt_L`, which makes setting the layout as US international preferable. See #Keymap table.)
Mode_switch
  The Mode_switch modifier may be mapped by default to a key that is not on your keyboard.

Note The usage of the modifier names `ISO_Level3_Shift` and `Mode_switch` is different between xmodmap and X Keyboard Extension. See also [2].

### Reassigning modifiers to keys on your keyboard

Note xmodmap is case-sensitive. Using incorrect case, such as `Mode_Switch` instead of the correct `Mode_switch` will cause errors.

Before assignment, the modifier keys need to be cleared. This applies to both modifiers you intend to assign and modifiers on keys that you intend to use. For example, if you intend to assign `Caps_Lock` to your A key and `B` to your NumLock key, you need to first clear the modifiers for both `Caps_Lock` and `Num_Lock`, then assign the keysyms, and finally add back the modifiers.

    ~/.Xmodmap

    [...]
    clear lock
    clear mod2
    keycode  38 = Caps_Lock
    keycode  77 = Num_Lock
    add lock = Caps_Lock
    add mod2 = Num_Lock

`!` 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.

The following example modifies `CapsLock` to `Control`, and `Shift+CapsLock` to `CapsLock`:

    ~/.Xmodmap

    clear lock
    clear control
    add control = Caps_Lock Control_L Control_R
    keycode 66 = Control_L Caps_Lock NoSymbol NoSymbol

## Compose key

This article or section is a candidate for merging with Xorg/Keyboard configuration#Configuring compose key.

Notes: Duplicate of Xorg/Keyboard_configuration#Configuring_compose_key (Discuss in Talk:Xmodmap)

A compose key serves to create special characters and symbols that may not be directly accessible on the keyboard. This is especially useful for typing accented letters from non-English languages. For example, pressing `Compose` `e` `'` in succession will produce é. Some characters require more than 2 keys to be pressed after `Compose`. Usually a modifier key of choice is mapped to `Compose`. The compose key can be set in the GUI settings of most desktop environments, but these options will not work if a custom key map table is used as described in this article. To set the compose key using `Xmodmap`, use the `Multi_key` identifier. For example, to map the right alt key (`AltGr`) to the compose key:

    ~/.Xmodmap

    [...]
    keycode 108 = Multi_key Alt_R Meta_R Alt_R Meta_R

The keycode number could vary based on keyboard models.

## Reverse scrolling

This article or section is a candidate for merging with Mouse buttons.

Notes: xmodmap is not the only way to do this. (Discuss in Talk:Xmodmap)

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

## Swapping mouse buttons

This article or section is a candidate for merging with Mouse buttons.

Notes: xmodmap is not the only way to do this. (Discuss in Talk:Xmodmap)

The left, middle and right mouse buttons correspond to buttons 1,2 and 3 respectively in the synaptics driver. To swap left and right mouse buttons, again simply reverse the order in which they are listed in your `~/.Xmodmap`:

    ~/.Xmodmap

    pointer = 3 2 1

This should suffice for a simple mouse setup. Again, 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

### Esperanto

Next is an example to make it possible to type Esperanto letters by pressing `AltGr` and the relevant letter. For example, if you type `AltGr+C`, you will get the letter "Ĉ".

    ~/.Xmodmap

    keycode 54 = c C c C ccircumflex Ccircumflex
    keycode 42 = g G g G gcircumflex Gcircumflex
    keycode 43 = h H h H hcircumflex Hcircumflex
    keycode 44 = j J j J jcircumflex Jcircumflex
    keycode 39 = s S s S scircumflex Scircumflex
    keycode 30 = u U u U ubreve Ubreve

### Turn CapsLock into Control

Simplest example of changing `CapsLock` into `Control`.

    ~/.Xmodmap

    clear lock
    clear control
    keycode 66 = Control_L
    add control = Control_L Control_R

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

Laptop users may prefer having `CapsLock` as `Control`. The `Left Control` key can be used as a `Hyper` modifier (an additional modifier for emacs, openbox or i3).

    ~/.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

### Turn Super_R into Hyper_R

Users who wish to have a `Hyper` key on full keyboard layout may wish to use the Right `Super` key as `Hyper`.

    ~/.Xmodmap

    remove  mod4 = Super_R
    keycode  134 = Hyper_R
    add     mod3 = Hyper_R

### 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

- xmodmap(1)
- Multimediakeys with .Xmodmap HOWTO by Christian Weiske
- Mapping unsupported keys with xmodmap by Pascal Bleser
- LQWiki:List of Keysyms Recognised by Xmodmap

Categories:

- Keyboard configuration
- Xorg commands

Hidden categories:

- Pages or sections flagged with Template:Expansion
- Pages or sections flagged with Template:Merge

xmodmap
Add topic