How to load your Xmodmap file on a modern Linux desktop

published Jun 06, 2022

Albeit this tip is only for X11 users — not necessarily Wayland users — it's nonetheless surprisingly easy.

How to load your Xmodmap file on a modern Linux desktop

Xmodmap files are files that let you set up your own keyboard mapping — the mapping that governs "key code" to "symbol" translation, e.g. key code 4 becomes the letter a.  Though the use of Xmodmap files has fallen by the wayside these days — with modern Linux distributions completely ignoring them when you log in — there are still quite a few valid uses.

Why even use Xmodmap files?

Useless key in 2022... unless...

For example, in my case, I have a FLIRC remote receiver, which lets me configure multimedia keys on any universal remote, so I can govern media playback from my couch.  The problem with the FLIRC remote receiver is that what it thinks the "pause" key is, is in fact the old school Pause key, rather than the new Media Pause key.  That is, of course, worthless if what you're trying to do is actually pause your music or movie!

No worries, though — Xmodmap to the rescue!  I have no use for the Pause key that the FLIRC receiver sends to the computer, so might as well remap the Pause key to the actual Media Pause key I actually want.  For that, I just add to my user's .Xmodmap file:

keycode 127 = XF86AudioPause

Presto!  Now the keycode 127, which normally is mapped to Pause, is now mapped to XF86AudioPause.

How to autoload Xmodmap files on login?

To autoload your .Xmodmap (and the system global /etc/X11/Xmodmap) file, put the following contents in file /etc/xdg/autostart/Xmodmap.desktop:

[Desktop Entry]
Comment=Load global and per-user Xmodmap file
Exec=/usr/bin/bash -c "for f in /etc/X11/Xmodmap ~/.Xmodmap ; do test -f $f && xmodmap $f || true ; done"

That file will cause your system to run that Exec= command upon every standard graphical login.

Now log out, and then log back in.

Voilà!  Whatever mappings you added to your Xmodmap files are now loaded.


If mappings are not loading, step 1 is to run xmodmap /path/to/your/.Xmodmap file and see if you get errors.

You can also look through your session's logs by running journalctl --since=today on a terminal window.