Originally posted on Rolling Release. I’m reposting this here as I recently broke my finger and so made a few changes to my xmodmap settings to accomodate the ensuing one-handed typing. Once again, I had to search for how to use xmodmap and came upon my own post. I’m keeping it here for easier reference and in the hope the details will burn deeper into my mind. It was written for a tutorial column so excuse the tone.

About xmodmap

Xmodmap is used to control the mappings between the keys you press on the keyboard and the results you will experience on screen. Some common usage examples of xmodmap are:

  • Disabling and/or reallocating the caps-lock key
  • Mapping certain foreign or other special characters to keys on your keyboard
  • Enabling “media” keys
  • Terminology

To achieve things like the above, you’ll be mapping KeyCodes to KeySyms and KeySyms to Modifiers so it’s obviously important to understand exactly what xmodmap means by these terms (I certainly didn’t when I started out).


A KeyCode is a number generated by your keyboard when you press a certain key. For example, the space bar usually produces the KeyCode 128.


A KeySym is simply a word used to name a type of key. This concept is very important because it means that applications don’t need to interpret the information output by your keyboard directly; they can refer to keys by name.

As mentioned above, most keyboards produce the code 128 when you press the spacebar but it would be possible to have a very non-standard keyboard that outputs the KeyCode 64 when the spacebar is pressed. You’d certainly want to ensure that code 64 is interpreted as a spacebar press without having to rewrite all the applications you use. To do this, we’d map the KeyCode 64 to the KeySym “space”.


A Modifier is a special kind of key that can be held at the same time as another key and modify its output. For example, when you press the A key on your keyboard, you see the letter ‘a’ appear on screen. If you hold shift and press A, you’ll see the letter ‘A’ – shift is a Modifier.

Let’s start with looking at modifiers to get the hang of Modifiers and KeySyms…


There are 8 modifiers:

  • Shift
  • Lock
  • Control
  • Mod1
  • Mod2
  • Mod3
  • Mod4
  • Mod5

Xmodmap provides three different operations for changing the way KeySyms are mapped to Modifiers: clear, add, and remove.

My favourite example – turning off caps lock:

$ xmodmap -e "clear Lock"

This command clears the Lock modifier meaning that no keys now produce a caps lock effect. Bliss!

To reassign the caps lock key to do something more useful:

$ xmodmap -e "add Shift = Caps_Lock"

This adds the KeySym “Caps_Lock” to the list of keys that produce the Shift modifier. In other words, we’ve turned caps lock into another shift key.

If you change your mind and want to stop the caps lock key behaving as a shift key:

$ xmodmap -e "remove Shift = Caps_Lock"

This is basically the opposite of the previous example.

Mapping KeyCodes to KeySyms

Now we’ve got the hang of changing the Modifiers, we’ll round off by looking at mapping the physical keys on your keyboard to produce the results you want.

First things first, you’ll need to know the keycode of the key you want to change. To do this, you can use xev.

$ xev

After running xev, press the key in question and you’ll see some output like this in your terminal:

KeyPress event, serial 21, synthetic YES, window 0x800001,
root 0x40, subw 0x0, time 1539131, (69,8), root:(683,402),
state 0x0, keycode 63 (keysym 0xfe03, ISO_Level3_Shift), same_screen YES,
XLookupString gives 0 bytes:
XmbLookupString gives 0 bytes:
XFilterEvent returns: False

The third line is the one we’re interested in. You’ll see the word keycode followed by the number you’re going to need next, in the example above it’s 63.

Now we’re going to map that key to give us some foreign characters.

$ xmodmap -e "keycode 63 = e E eacute Eacute"

The “keycode” command maps a KeyCode to a number of KeySyms. The order of the KeySyms is important as it represents how the KeySyms are derived.

  1. The key pressed alone
  2. With the Shift modifier
  3. The key pressed along with the Mode_switch key
  4. With Mode_switch AND Shift

Mode_switch is just another keysym and you can map it to a chosen key on your keyboard like this:

$ xmodmap -e "keycode 64 = Mode_switch"

My personal choice is to map Mode_switch to my AltGr key. To do this, you can use a special version of the keycode command. $ xmodmap -e “keycode Alt_R = Mode_switch” This asks xmodmap to lookup what keycode(s) are currently assigned to the KeySym Alt_R (right alt) and assign them to Mode_switch as well.

So with the above mappings, here’s what happens when I press the keys on my keyboard:

  • The key on it’s own -> A lowercase ‘e’

  • With shift -> An uppercase ‘E’

  • With AltGr -> A lowercase e-acute (as used in French for example)

  • With AltGr and shift -> An uppercase E-acute

Saving Your Mappings

Once you’ve decided how you’d like everything set up, you obviously don’t want to have to type all those xmodmap lines in every time you start X. To save you from this, you can just put all your mapping into a file (I save mine at ~/.xmodmap) and then just tell xmodmap to load from it.

$ xmodmap ~/.xmodmap

Ideally, you’d add that line to your .xinitrc so it runs automatically when you start X.

The End

That just about wraps up this howto. I hope somebody finds it useful as I certainly found xmodmap confusing in my early days. Now I have my keyboard customised to do just what I want and I couldn’t live without it.

A few useful links about xmodmap.