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 USB Keyboard Scancode Reference, Physical Key Layouts]
• 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.

To find keycode / keysym of a key, use the xev command. 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. Alt Graph+‹key›
6. Alt Graph+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 file_name.

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, …}.)

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?

Note: xmodmap is only for apps running under X11 (the Graphical Window system). For example, 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)