Set up key mappings with .Xmodmap

This is a guide for those who need to set up a custom Xmodmap for their keyboard. The worst thing one can do is to just copy a custom Xmodmap found on the internet without understanding how it works. You should use whatever existing mapping you already have (you must have one which works by default), and make modifications on top of it.

Here’s what you do (in a terminal, from your $HOME dir, as a regular user):

Export current mappings:

xmodmap -pke > modmap
xmodmap -pm >> modmap

Edit the “modmap” file, right at the end you’ll have a section which looks like this:

xmodmap:  up to 3 keys per modifier, (keycodes in parentheses):

shift       Shift_L (0x32),  Shift_R (0x3e)
lock        Caps_Lock (0x42)
control     Control_L (0x25),  Control_R (0x6d)
mod1        Alt_L (0x40),  Meta_L (0x9c)
mod2        Num_Lock (0x4d)
mod3
mod4        Super_L (0x7f),  Hyper_L (0x80)
mod5        Mode_switch (0x5d),  ISO_Level3_Shift (0x71),  ISO_Level3_Shift (0x7c)

This will have to be adapted to a xmodmap-compliant syntax, until it looks similar to the code below (don’t worry it’s really simple to adapt):

add shift =      Shift_L  Shift_R
add lock  =      Caps_Lock
add control =    Control_L  Control_R
add mod1    =    Alt_L Meta_L
add mod2    =    Num_Lock
add mod3    =    Mode_switch
add mod4    =    Super_L  Hyper_L
add mod5    =    ISO_Level3_Shift
keysym Alt_R = Mode_switch

What I did was map the Alt_R key to the Mode_switch mode, which will allows special modes for keys, like special symbols and stuff. I added the Mode_switch mode to mod3 because mod3 was not being used by anything else. You should do the same.

When you’re done, save the file and try it to see if it works:

xmodmap modmap

It should work, but it is also possible to fail with some unexplainable error like “couldn’t find keycode for Alt_R”, although that keycode is well defined within the modmap file. If that’s the case, we shall hack our way around it:

xmodmap -e "keycode 108 = Alt_R"

(Note that on a different keyboard Alt_R might have another keycode (check the modmap file, or else use xev).

You can also use the above command if you only want to make a slight modification (e.g. add a single key):

xmodmap -e "keycode xxx = my_key my_new_mapping"

The next step is to assign our special characters to keys (so they would be available with Alt_R+key). Find out the codes of the characters you want to use from a table like this one: http://biega.com/special-char.html.

keycode  24 = q Q 0x000e2 0x000c2
keycode  25 = w W U003c9 U003a9
keycode  27 = r R U003C1 U003A1
keycode  28 = t T U00163 U00162
keycode  30 = u U U000FC U000DC
keycode  31 = i I 0x000ee 0x000ce
keycode  32 = o O U000F6 U000D6
keycode  33 = p P U003C0 U003A0
keycode  38 = a A U00103 U00102
keycode  39 = s S U0015f U0015e
keycode  40 = d D U003B4 U00394
keycode  42 = g G U003B3 U00393
keycode  46 = l L U003BB 0039B

Once you’re done, reload the file, and rename it to .Xmodmap, so it will be automatically loaded next time you log into X (you can also try dropping a line in your .xinitrc, with the xmodmap command).

xmodmap modmap
mv modmap ~/.Xmodmap

That’s it! At this point you should be able to enjoy your new key mappings :)