Convert a Linux Keytable into an Xmodmap File with mk_modmap

If your X keyboard mapping needs fixing but all you have is a Linux console keytable, mk_modmap is the small tool that turns one into the other. It writes the converted file to standard output, so you can inspect it before saving or applying anything. Allow about 10 minutes for a one-off conversion, plus time to check the result on the target X session.

Before you start

• The kbd package. On this machine, that is kbd 2.6.4-2ubuntu2.
• A Linux keytable file to convert.
• The X header file /usr/include/X11/X.h. The installed command checks that exact path before it reads the keytable, since it reads X keysym definitions as part of the translation.

The manpage describes the command as a translator and lists dumpkeys, keymaps and xmodmap as related tools.

Check the executable and prerequisite as your normal user:

command -v mk_modmap
test -f /usr/include/X11/X.h && echo "X header is present"

Expect a path such as /usr/bin/mk_modmap followed by X header is present. If the header test fails, install the package that supplies your distribution's X development headers. Do not work around it by creating a dummy header file, the converter genuinely needs the real definitions.

1. Get a source keytable

If you already have a keytable file, use its path in the next steps. To ask the running virtual console for its current table instead, try:

dumpkeys > "$HOME/current-keytable.map"

This reads the keyboard driver and writes a file in your home directory. It normally needs no elevated privileges, but it can fail in a container, an SSH-only session, or anywhere without a usable virtual console. That failure says nothing about mk_modmap itself: just use a keytable exported on the machine where the console actually exists.

Before converting a supplied file, identify it explicitly. Do not use an untrusted path copied from a web page or an email:

keytable="$HOME/current-keytable.map"
test -r "$keytable" && echo "Reading: $keytable"

A keytable contains entries such as keycode 30 = a A and names such as AltGr or BackSpace. It is input data, not an executable script.

2. Convert and inspect the output

Run the converter with the keytable as its only positional argument:

mk_modmap "$keytable" > "$HOME/current-xmodmap.xmodmap"
sed -n '1,40p' "$HOME/current-xmodmap.xmodmap"

Expect output that starts with comments followed by commands like these, though the timestamp and key mappings depend on your input:

! Converted keytable file to xmodmap file
clear Mod1
clear Mod2
keycode  38 =  a A
add Mod1 = Alt_L
add Mod2 = Mode_switch

This is not a straight copy of Linux keycodes. The installed script translates ordinary keycodes for X and has special handling for modifier keys, keypad and navigation keys, AltGr, dead keys and several named keysyms, so review the whole output for anything unexpected. A comment carried over from the input turns up as an Xmodmap comment in the generated file, which is handy when you are tracing a suspicious line.

Redirecting the output creates or replaces the destination file, which changes state. For a no-write preview, send it to the terminal instead:

mk_modmap "$keytable" | sed -n '1,40p'

mk_modmap never loads the result into X itself, it only prints the translation. Treat a generated file as configuration until you have checked it against the physical keyboard and the X session where it will actually be used.

3. Catch skipped entries with verbose mode

The -v option turns on diagnostic messages. Keep normal output in the file and send diagnostics to a separate file, so the Xmodmap syntax stays clean:

mk_modmap -v "$keytable" > "$HOME/current-xmodmap.xmodmap" \
  2> "$HOME/mk_modmap.log"
cat "$HOME/mk_modmap.log"

On the installed version, verbose diagnostics include a message whenever an input keycode is skipped because it cannot be represented in the supported X range. An empty log is a good result. Do not concatenate the diagnostic file into the generated configuration.

4. Apply the file safely

Applying an Xmodmap file can alter the keyboard mapping for the current graphical session. It does not need mk_modmap to run as root, and using sudo here can put the file in the wrong user's environment. Save the working mapping first, then apply only after reviewing the generated text:

xmodmap -pke > "$HOME/before-mk_modmap.xmodmap"
xmodmap "$HOME/current-xmodmap.xmodmap"

These commands affect the current X display. If the result is wrong, restore the previous mapping with:

xmodmap "$HOME/before-mk_modmap.xmodmap"

If xmodmap reports that no display is available, you are probably in a non-graphical session or using a display without the required authentication. That is an environment problem, not evidence the translation is wrong. Also bear in mind that modern X setups often initialise straight from the Linux keymap, so a generated file may not even be necessary. Do not add it to session startup merely because the conversion succeeded.

Common traps

• Missing X headers: the command exits before conversion when /usr/include/X11/X.h is absent. Check the exact path rather than guessing from the package name.
• Wrong input format: mk_modmap expects a Linux keytable, not an existing Xmodmap file. Confirm the first meaningful lines contain Linux keytable declarations.
• Mixed standard output and diagnostics: use 2> with -v. Xmodmap input should not contain verbose messages.
• Assuming conversion applies changes: it does not. Loading the result is a separate, potentially disruptive action.
• Overlooking old assumptions: the installed manpage dates from 2002, while this machine has kbd 2.6.4. Trust the locally installed command's actual output and test it in the target session.

Done means

• The source is a readable Linux keytable.
• The X header prerequisite is present.
• The generated Xmodmap file was reviewed, with verbose diagnostics checked separately.
• The original X mapping was saved before any test application.
• You can restore the previous mapping with xmodmap "$HOME/before-mk_modmap.xmodmap".