Print an XKB Keyboard Layout to PostScript with xkbprint

You will produce a PostScript keyboard chart from a compiled XKB keymap, with readable key labels and an optional colour rendering. This is useful when reviewing a layout, documenting a custom keyboard, or checking what a keymap actually contains without changing the active X server.

Allow about 10 minutes if you already have an .xkm file. You need the xkbprint command from the x11-xkb-utils package, plus a compiled keymap that includes geometry. The examples here were checked with Debian/Ubuntu package x11-xkb-utils 7.7+8build2, whose program reports xkbprint 1.0.6. No root access is needed: write the output somewhere you can edit.

Checkpoint: confirm the local tool

1. Check the installed version before relying on a flag.

   xkbprint -version
   dpkg-query -W -f='${Package} ${Version}\n' x11-xkb-utils

Expected output includes:

xkbprint 1.0.6
x11-xkb-utils 7.7+8build2

The package version matters because the installed help can expose options that an older local manpage does not describe. This guide sticks to the documented options in the installed xkbprint(1) page.

1. Start with a keymap that has geometry

xkbprint accepts either an X display specification or a compiled keymap file. For a file, the keymap must include geometry. A symbols file on its own is not enough to draw a keyboard: symbols say what keys mean, while geometry says where the keys are.

If another tool has already produced an .xkm file, inspect it without modifying it:

file /path/to/layout.xkm

Continue when the result identifies a compiled XKB keymap. If you only have source fragments, compile a complete keymap first. The following small example uses the system XKB data and writes only to /tmp:

workdir=$(mktemp -d /tmp/xkbprint.XXXXXX)
xkbcomp -xkm -I/usr/share/X11/xkb -w 0 - "$workdir/us.xkm" <<'EOF'
xkb_keymap {
  xkb_keycodes { include "evdev" };
  xkb_types { include "complete" };
  xkb_compat { include "complete" };
  xkb_symbols { include "pc+us" };
  xkb_geometry { include "pc(pc105)" };
};
EOF
file "$workdir/us.xkm"

Expected output identifies us.xkm as a compiled XKB keymap. This compilation step does not install anything or alter your keyboard. Keep the temporary directory until you have checked the PostScript, then remove it with rm -r -- "$workdir". That removes only the directory created by the command.

2. Make a readable black-and-white chart

Use -o to choose the output path explicitly. The default is a fitted keyboard image, and -mono requests the default black-and-white rendering. -label name puts key names on the keys, which is usually the clearest first inspection.

xkbprint -mono -fit -label name \
  -o "$workdir/us-names.ps" \
  "$workdir/us.xkm"
file "$workdir/us-names.ps"
wc -c "$workdir/us-names.ps"

Expected output from file describes a PostScript document. A non-zero size from wc confirms that an output file was written. Open the file in a PostScript viewer or convert a copy to PDF if that is more convenient:

ps2pdf "$workdir/us-names.ps" "$workdir/us-names.pdf"
file "$workdir/us-names.pdf"

Do not use a privileged command to make this chart. If a viewer refuses to open it, check the file type and the command's exit status first; do not fix permissions by making the file world-writable.

3. Choose labels and page layout deliberately

The -label value can be none, name, code, or symbols. Names are good for understanding the keymap. Keycodes are useful when comparing hardware-oriented definitions. Symbols show the bindings that a user normally sees.

xkbprint -mono -fit -label symbols \
  -o "$workdir/us-symbols.ps" \
  "$workdir/us.xkm"

-fit is the default and scales the keyboard to the page. Use -full when the physical size matters more than fitting one page. That can create a large drawing, so check the result before sending it to a printer.

For a colour diagram, use the colour option shown below. The colour information comes from the geometry definition, so a geometry with no meaningful colour differences may look much like the monochrome result. Treat colour as assistance, not as the only distinction in documentation.

xkbprint -color -fit -label name \
  -o "$workdir/us-colour.ps" \
  "$workdir/us.xkm"

4. Use an EPS file when another tool needs it

Use -eps for Encapsulated PostScript. Give it an explicit filename so an automated job cannot surprise you by choosing a derived name.

xkbprint -eps -mono -label symbols \
  -o "$workdir/us.eps" \
  "$workdir/us.xkm"
file "$workdir/us.eps"

When no output filename is supplied, xkbprint derives one from the source: it replaces the source extension with .ps, or with .eps when EPS output is requested. With a display source, the derived name is based on the display specification. Relying on that default is a common distraction when a script later looks for a differently named file, so -o is safer in repeatable work.

5. Diagnose the usual failures

• Cannot read geometry: the input is missing a geometry section or is not a compiled keymap. Compile a complete keymap, then check it with file.
• Cannot open the display: a display source such as :0 needs a reachable X server and suitable authorisation. Use a local .xkm file when you are documenting a saved layout.
• The chart is too small: use -full, or keep -fit and reduce the number of keyboards per page with the layout choices in your publishing tool.
• Labels are missing or confusing: try -label name, then -label code or -label symbols. The -dflts option asks xkbprint to compute names for missing components, but it does not repair an incomplete keymap.
• Output is empty or unexpectedly short: stop before printing it. Run xkbprint -version, repeat with -w 10 for the highest warning level, and inspect the command's exit status.

These commands only read the keymap and write a PostScript or EPS file. They do not load a layout, alter XKB configuration, restart a service, or require elevated privileges. Deleting a generated file is irreversible unless you can recreate it, so keep the source .xkm and remove only outputs you no longer need.

Done means

• xkbprint -version reports the version you checked.
• The input is a compiled XKB keymap with geometry.
• xkbprint exits successfully and file identifies the output as PostScript or EPS.
• The chart has the label type, scale and colour mode you intended.
• The original keymap is still available if you need to regenerate the chart.