Compile and Inspect XKB Keymaps with xkbcomp

xkbcomp compiles an XKB source description into a compiled keymap, or unpacks one back into resolved source for inspection. It also draws a sharp line between writing a file and changing a running X display. The examples target xkbcomp 1.4.6 from Debian package x11-xkb-utils 7.7+8build2.

Allow about 15 minutes if you already have an .xkb, .xkm or display to work with. The command is normally run as your own user. The examples write only under /tmp; no elevated privileges are needed.

1. Check the installed command

Confirm which executable will run and record its version before comparing output with another machine. This matters because XKB behaviour and the available options belong to the installed xkbcomp release.

$ command -v xkbcomp
/usr/bin/xkbcomp
$ xkbcomp -version
xkbcomp 1.4.6

If the first command prints nothing, install the distribution package that provides xkbcomp. Do not copy a binary from another host: its include directory and parser version may differ from the files on this system.

2. Understand the input and output pair

The general form is xkbcomp [option] source [destination]. The source can be an X display, an .xkb source file or an .xkm compiled keymap. With no explicit output format, xkbcomp chooses a sensible destination format from the source: an .xkb source normally becomes an .xkm file, while an .xkm file or display normally becomes resolved .xkb source.

Make the destination explicit when a script or review depends on a particular file name. The -xkm option asks for a compiled keymap and -xkb asks for source output. The -o option supplies the output path.

$ xkbcomp -xkm -o /tmp/keyboard.xkm /path/to/keyboard.xkb
$ xkbcomp -xkb -o /tmp/keyboard-resolved.xkb /path/to/keyboard.xkm
$ file /tmp/keyboard.xkm /tmp/keyboard-resolved.xkb

Replace /path/to/keyboard.xkb with a real, complete XKB keymap. A symbols fragment such as /usr/share/X11/xkb/symbols/us is not the same thing as a complete keymap and should not be used as a stand-alone input for this workflow.

Checkpoint: You should have a source file as input and a new file under /tmp. If compilation fails, preserve the diagnostic and fix the source before trying another option.

3. Inspect a resolved keymap without changing the display

Resolved output is useful when an XKB description includes several files. It shows the merged result that xkbcomp can parse, so it is a practical way to inspect include resolution and derived details. Add -a when you want implicit or derived information shown as comments in XKB source output.

$ xkbcomp -xkb -a -o /tmp/keyboard-resolved.xkb /path/to/keyboard.xkb
$ sed -n '1,40p' /tmp/keyboard-resolved.xkb
$ grep -n 'xkb_symbols\|xkb_keycodes\|xkb_types' /tmp/keyboard-resolved.xkb

This is a file operation. It does not load anything into an X server because the destination is a path. If you need a reproducible review, keep the original source beside the resolved output and compare them with diff -u. The resolved file may be much larger because included components have been expanded.

4. Control included files deliberately

XKB descriptions often include components by relative name. The -I option adds a top-level directory to the search path. After the directories named by -I, xkbcomp normally searches the current directory and then /usr/share/X11/xkb.

$ xkbcomp -I/path/to/xkb-root -xkb -o /tmp/keyboard-resolved.xkb /path/to/keyboard.xkb

To stop xkbcomp searching the current and default directories, give a bare -I before the directories you do want searched. This is a useful boundary when reviewing untrusted input, because it prevents an accidental file in the working directory from satisfying an include.

$ xkbcomp -I -I/path/to/xkb-root -xkb -o /tmp/keyboard-resolved.xkb /path/to/keyboard.xkb

Use -R when the source uses relative paths that should be interpreted beneath a particular root. Keep -I and -R separate in your notes: the former controls include search directories, while the latter sets the root for relative path names.

5. Read warnings and choose a strictness level

The warning level is controlled by -w. Level 0 disables warnings, while level 10 enables all warnings. Start with the default behaviour, then increase the level when checking a keymap for avoidable problems. Do not hide warnings merely to make a build log shorter.

$ xkbcomp -w 10 -xkb -o /tmp/keyboard-resolved.xkb /path/to/keyboard.xkb

For scripts, the message options can add a recognisable prefix before the first error, at the start of each message line, or before exit when errors occurred. For example, -emp 'xkbcomp: ' makes compiler output easier to find in a larger log. Quote the message so the shell passes it as one argument.

6. Treat display destinations as a change

Warning: If the destination is an X display, xkbcomp updates that display's keymap. That is a live configuration change and can affect every client using the display. It can also make the keyboard behave unexpectedly if the description is wrong. Test by writing a file first, and keep a known-good keymap or a second session available before loading anything into a display.

$ xkbcomp /path/to/keyboard.xkb :0

The display name is an example placeholder, not a guarantee that display :0 exists. On a headless shell this command should fail with a display connection error. That failure is preferable to silently assuming a live X server is available. A destination that names a file, such as /tmp/keyboard.xkm, does not make this live change.

Options such as -i select a device ID when the source or destination is a display. Use that only when you have identified the correct X input device and understand the effect. It is not needed for ordinary file compilation.

7. Diagnose the common traps

If an output file is wrong, remove only that generated file or replace it with a known-good copy. The commands above do not alter the installed XKB database. If you did load a map into a display and need to recover, reconnect to the session's normal keyboard configuration or restart the X session according to your desktop's own recovery procedure.

Done means