From ArchWiki
Jump to: navigation, search

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. [1]


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

The keycode is the numeric representation received by the kernel when a key or a mouse button is pressed.
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.


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 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 from xorg.conf or add, using us layout as an example, setxkbmap -layout 'us(intl)' before calling xmodmap.

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:

if [ -s ~/.Xmodmap ]; then
    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 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.

!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:

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

Reverse scrolling

Merge-arrows-2.pngThis article or section is a candidate for merging with Mouse buttons.Merge-arrows-2.png

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:

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

Then update xmodmap:

$ xmodmap ~/.Xmodmap

Swapping mouse buttons

Merge-arrows-2.pngThis article or section is a candidate for merging with Mouse buttons.Merge-arrows-2.png

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:

pointer = 3 2 1

This should suffice for a simple mouse setup. Again, update xmodmap:

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

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.

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