Debugging

Available tools

xkbcommon provides multiple CLI tools for debugging, grouped under the xkbcli application. Please consult the manual pages `man xkbcli` for the complete documentation of each tool.

Note

These tools may not be installed by default; please ensure you have the libxkbcommon-tools package installed.

xkbcli interactive

Test your configuration interactively. It chooses the appropriate backend based on the session type. Alternatively you may select explicitly the backend:

xkbcli interactive-wayland

Test in a Wayland session.

xkbcli interactive-x11

Test in an X11 session.

xkbcli interactive-evdev

Test raw input events directly. This requires access to the /dev/input/event* devices, you may need to add your user to the input group or run as root.

Remarks

You may want to use the flag --enable-compose if your layouts use dead keys.

xkbcli dump-keymap

Dump an XKB keymap from a display server. It chooses the appropriate backend based on the session type. Alternatively you may select explicitly the backend:

xkbcli dump-keymap-wayland

Dump an XKB keymap from a Wayland compositor.

xkbcli dump-keymap-x11

Dump an XKB keymap from an X11 server.

xkbcli how-to-type

Find the required key combinations to produce a specific character or keysym.

xkbcli list

List available layouts, variants, and options provided by an XKB database.

xkbcli compile-keymap

Compile a keymap and inspect its properties.

Remarks

Use the options --explicit-* to force the corresponding values to be explicit. This is especially useful to debug compatibility interpretations.

xkbcli compile-compose

Compile Compose files.

xkbcli info

Print information about xkbcommon configuration.

Error index

Each error has a unique identifier printed as [XKB-nnn] in the log.

See the error index for the documentation of each error.

Testing a custom configuration

Note

An erroneous XKB configuration may make your keyboard unusable. Therefore it is advised to try custom configurations safely with the following workflow:

1. Create a directory for the custom configuration, e.g. ~/xkb-test. Note that in order to test it safely, it should not be one of the locations that xkbcommon searches.
2. Create the relevant sub-directories and files, e.g. ~/xkb-test/symbols/my-layout.

3. Test if your changes compile successfully:

   xkbcli compile-keymap --include ~/xkb-test --include-defaults --test --layout my-layout

   Note

   The order of the --include* arguments is important here.

   If it does not compile, you may add the flag --verbose for additional information.

4. Test if it behaves correctly. Note that you may need to add your user to the input group or run as root.

   xkbcli interactive-evdev --include ~/xkb-test --include-defaults --enable-compose --layout my-layout

5. Repeat steps 3 and 4 with your full keyboard configuration, i.e. all your model, layouts and options.
6. If everything works as expected, it is time to test in real conditions:
   • Wayland: , move ~/xkb-test to one of the user-configuration locations, restart your session, update the keyboard configuration using your usual UI and enjoy your XKB customization!

   • X11: Unfortunately Xorg does not support alternative paths, so the next best option is to use the venerable xkbcomp tool.

     xkbcli compile-keymap --include ~/xkb-test --include-defaults --layout my-layout \
       | xkbcomp - $DISPLAY

Happy hacking!