Linux: xmodmap Tutorial

This page is a tutorial on Linux X11's xmodmap tool.

Here's a quick example. I need to temporarily swap {Return, End} keys.

Creat a file at ~/.Xmodmap with this content:

! -*- coding: utf-8 -*-
! swap keys {return, end}

! keycode  36 = Return NoSymbol Return
! keycode 115 = End NoSymbol End

keycode  36 = End NoSymbol End
keycode 115 = Return NoSymbol Return

Then run xmodmap ~/.Xmodmap.

xmodmap Tutorial

X11 has concepts of “keycode” and “keysym”.

Scancode

A number your keyboard sends to a computer. For USB keyboards, it's defined by the USB standard. [see Linux: Find Keyboard Key Scancode]

Keycode

A number used by Linux kernel to represent key (or mouse button/wheel). The Linux kernel translates scancode to keycode.

Keysym

A name for a key. Keysym is received by X11 applications. [see Linux: X11 Keyboard Key Names]

Type xmodmap -pke to see your current keycode / keysym mapping.

Type xmodmap -pke > ~/xmodmap_original to save a version of your mapping before you change anything.

To revert to default keymap, just type xmodmap ~/xmodmap_original.

Here's a full dump of default mapping from my machine and keyboard: xmodmap_dump_2013-01-11.txt

Here's sample output:

keycode  57 = n N n N
keycode  58 = m M m M
keycode  59 = comma less comma less
keycode  60 = period greater period greater
keycode  61 = slash question slash question
keycode  62 = Shift_R NoSymbol Shift_R
keycode  63 = KP_Multiply KP_Multiply KP_Multiply KP_Multiply KP_Multiply KP_Multiply XF86ClearGrab
keycode  64 = Alt_L Meta_L Alt_L Meta_L
keycode  65 = space NoSymbol space
keycode  66 = Caps_Lock NoSymbol Caps_Lock
keycode  67 = F1 F1 F1 F1 F1 F1 XF86Switch_VT_1
keycode  68 = F2 F2 F2 F2 F2 F2 XF86Switch_VT_2

the left side is keycode, the right side is its meaning in keysym. The first keysym is the key pressed by itself, the others are with different modifier keys. The meanings are:

1. key by itself.
2. Shift+key
3. mode_switch+key
4. mode_switch+Shift+key
5. AltGraph+key
6. AltGraph+Shift+key

Each line of xmodmap -pke output is a expression that can be read by xmodmap.

For example, type xmodmap -e "keycode 67 = F2" to make F1 key send F2. The -e option means read in expression.

To revert, just xmodmap ~/xmodmap_original.

To create your own map, just create a file with xmodmap expressions, then have xmodmap read it xmodmap filename.

Load Your Keymap When X11 Starts

Name your xmodmap config file as ~/.Xmodmap. It'll automatically load if you are using Ubuntu.

or, create a file at ~/.xinitrc, with this content:

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

Examples

• Linux: Swap Control Alt Keys
• Linux: Swap CapsLock Escape Keys
• Linux: Disable Number Lock Key

Example: Make {F2 F3 F4} Do {Cut Copy Paste}

Creat a file at ~/.Xmodmap with this content:

! -*- coding: utf-8 -*-
! make f1 f2 f3 do cut copy paste

! keycode  68 = F2 F2 F2 F2 F2 F2 XF86Switch_VT_2
! keycode  69 = F3 F3 F3 F3 F3 F3 XF86Switch_VT_3
! keycode  70 = F4 F4 F4 F4 F4 F4 XF86Switch_VT_4

keycode  68 = XF86Cut F2 F2 F2 F2 F2 XF86Switch_VT_2
keycode  69 = XF86Copy F3 F3 F3 F3 F3 XF86Switch_VT_3
keycode  70 = XF86Paste F4 F4 F4 F4 F4 XF86Switch_VT_4

X11 has these keysyms {XF86Cut, XF86Copy, XF86Paste}. They represent dedicated {Cut, Copy, Paste} keys. (some keyboards have these keys. For example, Kinesis Freestyle • Sun Microsystems Type 6 Keyboard )

If you do this, some X11 apps will automatically recognize those key functions. For example, it works in Firefox. (as of 2015-03-26, it does not work in: {Google Chrome browser, gimp, inkscape, gnome-terminal}.)

If you want the key to actually sent control combination, see Linux: Set F2 F3 F4 to Cut Copy Paste

Example: Swap 1 8, 2 7

! ~/.Xmodmap
! 2015-06-15
! change number layout, but not the shifted symbols

! swap keys 8 and 1
keycode  17 = 1 asterisk 1 asterisk
keycode  10 = 8 exclam 8 exclam

! swap keys 7 and 2
keycode  11 = 7 at 7 at
keycode  16 = 2 ampersand 2 ampersand

[see Keyboard: What's the Most Efficient Layout for Numbers?]

Example: Set Up F13 F14 F15 Keys

I have a keyboard that has {F13, F14, F15, F16, F17} Keys. By default, they are mapped to some X11 function keys. (In Ubuntu Linux running xfce.)

F13

keycode 191 = XF86Tools NoSymbol XF86Tools

F14

keycode 192 = XF86Launch5 NoSymbol XF86Launch5

F15

keycode 193 = XF86Launch6 NoSymbol XF86Launch6

F16

keycode 194 = XF86Launch7 NoSymbol XF86Launch7

F17

keycode 195 = XF86Launch8 NoSymbol XF86Launch8

In xfce, the F13 (XF86Tools) key doesn't work for some reason. xev shows the key working fine, but X11 apps doesn't seem to receive any signal when F13 is pressed. F14 and others work fine.

I want {F13, F14, …} to be themselves.

So, i created a file at ~/.Xmodmap with this content:

! -*- coding: utf-8 -*-
! 2014-02-19

! set F13 and others to F keys as is

! keycode 191 = XF86Tools NoSymbol XF86Tools
! keycode 192 = XF86Launch5 NoSymbol XF86Launch5
! keycode 193 = XF86Launch6 NoSymbol XF86Launch6
! keycode 194 = XF86Launch7 NoSymbol XF86Launch7
! keycode 195 = XF86Launch8 NoSymbol XF86Launch8

keycode 191 = F13 F13 F13
keycode 192 = F14 F14 F14
keycode 193 = F15 F15 F15
keycode 194 = F16 F16 F16
keycode 195 = F17 F17 F17

With this, all F keys work. I can now proceed to do normal keybinding in emacs or other apps with standard F keys. [see Emacs: How to Define Keys]

How to Set Keys for Linux Console?

Xmodmap only works in X11. It does not change keys in Virtual Console. [see Linux: How to use Virtual Console] or linux console (the command line screen when boot up)

See: Linux: Set System Keyboard Layout