Linux: xmodmap Tutorial
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 cannot set a key to type key combinations such as Ctrl+c
- xmodmap cannot set a key to run a script.
- xmodmap key cannot change key based on which is current app.
For these, you'll need other tools, see: Linux: Keyboard Software Guide
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.
- 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
xmodmap -pke
output.
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:
- key by itself.
- Shift+key
- mode_switch+key
- mode_switch+Shift+key
- AltGraph+key
- 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 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
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 , 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
If you have a question, put $5 at patreon and message me.