Linux: xmodmap Tutorial

By Xah Lee. Date: . Last updated: .

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

What can xmodmap do?

xmodmap is only for remapping keys, for apps running under X11. That's it.

xmodmap example

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

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

! 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

What is Scancode Keycode Keysym

xmodmap command

xmodmap -pke
show current keycode / keysym mapping.
xmodmap -pke > ~/xmodmap_original
save current mapping to file

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

Xmodmap Syntax Meaning

Here's part of xmodmap -pke 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

There are several ways, some may not work, depending on your linux distro.

Method: xmodmap init

Name your xmodmap config file as

~/.Xmodmap

It'll automatically load if you are using Ubuntu.

Method: xprofile

Create a file at one of

with this content: 

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

Method: bash init

In your bash init file ~/.bash_profile , [see Bash Init (Profile), .bashrc .profile .bash_profile], add a line 

# load my xmodmap key init
xmodmap ~/.Xmodmap

How to Set Keys for Linux Console?

Xmodmap only works in X11. It does not change keys in Linux: Virtual Terminal nor linux console (the command line screen when boot up)

See: Linux: Set System Keyboard Layout

Linux xmodmap keybinding