Convert a Linux Keytable into an Xmodmap File with mk_modmap

Use mk_modmap to turn a Linux console keytable into text that xmodmap can read. The command 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

You need the kbd package, a Linux keytable file, and the X header file /usr/include/X11/X.h. The installed command checks that exact header path before it reads the keytable. On this machine, the package is kbd 2.6.4-2ubuntu2. 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"

Expected output includes a path such as /usr/bin/mk_modmap followed by X header is present. If the test fails, install the package that supplies the X development headers for your distribution. Do not work around the check by creating a dummy header: the converter reads X keysym definitions as part of its translation.

Checkpoint 1: obtain the 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, try:

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

This reads the keyboard driver and creates a file in your home directory. It normally does not require elevated privileges, but it can fail in a container, an SSH-only environment, or a session without a usable virtual console. That failure says nothing about mk_modmap; use a keytable exported on the relevant machine instead.

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.

Checkpoint 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"

Expected output starts with comments followed by commands like these, although the timestamp and key mappings depend on the input:

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

The conversion is not a 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. Review the complete output for unexpected mappings. A comment from the input is carried into the generated file as an Xmodmap comment, which is useful when tracing a suspicious line.

The redirection changes state by creating or replacing the destination file. If you want a no-write preview, send the output to the terminal instead:

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

mk_modmap does not load the result into X. It only prints the translation. Treat a generated file as configuration until it has been checked against the physical keyboard and the X session where it will be used.

Checkpoint 3: use verbose mode for skipped entries

The -v option enables diagnostic messages. Keep normal output in the file and send diagnostics to a separate file so the Xmodmap syntax remains 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 messages when an input keycode is skipped because it cannot be represented in the supported X range. An empty log is a useful result. Do not concatenate the diagnostic file into the generated configuration.

Applying the file safely

Applying an Xmodmap file can alter the keyboard mapping for the current graphical session. It does not require mk_modmap to run as root, and using sudo can put the file in the wrong user's environment. Preserve 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 that the translation is valid. Also remember that modern X setups often initialise from the Linux keymap, so a generated file may be unnecessary. Do not add it to session startup merely because 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. Prefer the locally installed command's 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".