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 :)

7 thoughts on “Set up key mappings with .Xmodmap

  1. Hans-J. Schmid

    Thank you very much. This is really the proper way to do it.

  2. spencer

    xmodmap: unknown command on line modmap:249
    xmodmap: unknown command on line modmap:251
    xmodmap: unknown command on line modmap:252
    xmodmap: unknown command on line modmap:253
    xmodmap: unknown command on line modmap:254
    xmodmap: unknown command on line modmap:255
    xmodmap: unknown command on line modmap:256
    xmodmap: unknown command on line modmap:257
    xmodmap: unknown command on line modmap:258
    xmodmap: 9 errors encountered, aborting.
    sneilan@ubuntu:~$ xmodmap modmap

    X Error of failed request: BadValue (integer parameter out of range for operation)
    Major opcode of failed request: 118 (X_SetModifierMapping)
    Value in failed request: 0×17
    Serial number of failed request: 262

    That is from adding this to the end my modmap file:

    keycode 254 =
    keycode 255 =
    add shift = Shift_L Shift_R (<- pasted from here)
    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

  3. -

    Thanks for the mod3 = Mode_switch tip, very neat, especially when it’s assigned it to the capslock on a keyboard with no caps leds.

    I had the same issues as spencer, if anyone else happens to need an answer.

    The “unknown command on line …” errors are because, on fedora 17 at least, the output of xmodmap -pm isn’t compatible with xmodmap -e. Inputting manually, or xmodmap -pm through grep & sed, seem to be the only solution.

    The “X Error of failed request: BadValue” was, in my case, related to Mode_switch already being assigned to mod5. Clearing whichever modifier the key was assigned to before setting the new modifiers is necessary.

    xmodmap -e ‘clear mod5′ -e ‘add mod5 = ISO_Level3_Shift’ -e ‘mod3 =…’

  4. Pingback: how do you reconfigure the 1..9 keyboard shorcuts in XMonad? | Technology & Programming Answers

  5. Pingback: Сборка AlexELECv3-20131212-r0018 | HTPC OS

  6. Pingback: xmodmap and key combinations (<Ctrl+C>) ?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s