Watch XKB Keyboard State Changes with xkbwatch

You will finish with xkbwatch running in an X session and reporting changes to the fundamental parts of the X Keyboard Extension (XKB) state, together with the effective compatibility state. This is a useful observation tool when checking layouts, modifiers or other keyboard-state changes. It does not edit the keyboard configuration.

The examples use xkbwatch 1.0.5 from the installed x11-xkb-utils package, version 7.7+8build2. Allow about ten minutes for a first check. You need a shell, the package installed, and access to the X display whose keyboard state you want to observe.

1. Confirm the installed program

Check which executable your shell will launch, then ask it for its version. Both commands are read-only:

$ command -v xkbwatch
/usr/bin/xkbwatch
$ xkbwatch -version
xkbwatch (xkbutils) 1.0.5

The manpage documents -version as the additional xkbwatch option. It prints the program version and exits. The package version and the program version are different identifiers: the former describes the distribution package, while the latter describes xkbutils itself.

2. Start it from the right display

Run xkbwatch from a terminal that belongs to the X session you want to inspect:

$ xkbwatch

The program is a graphical X client, so it needs a usable display connection. The installed binary gives this result when no display is available:

Error: Can't open display:

On a desktop terminal, the session normally provides the display environment for you. In a remote shell, a different virtual console, a scheduled job or a container, it may be missing or point at the wrong server. Check the value without changing it:

$ printf 'DISPLAY=%s\n' "${DISPLAY-}"

An empty value explains the failure, but setting a guessed display is not a reliable fix. Use the display value and authorisation method belonging to the target X session. If you are using SSH, X forwarding must be deliberately enabled and permitted by both ends. Do not copy another user's X authority cookie or weaken access control just to make a diagnostic window appear.

3. Observe a known keyboard change

Once xkbwatch is connected, its window reports changes in XKB's fundamental keyboard-state components and in the effective compatibility state. The exact values depend on the X server, keyboard layout and current input state, so do not treat a particular initial screen as universal.

Make one controlled change in the same X session, such as pressing and releasing a modifier key. Watch for the corresponding state update. Then change one variable at a time, for example by switching between layouts that are already configured in that session. This keeps the event you are investigating separate from unrelated desktop shortcuts.

4. Keep the test reversible

Stop xkbwatch with Ctrl-C in the terminal where it is running, or close its window through the desktop. Closing it ends the observer process; it does not undo or alter the XKB configuration. There is therefore no configuration rollback step for this guide.

$ xkbwatch
^C

If you launched it in the foreground and the terminal is needed for another command, use a new terminal rather than backgrounding an unknown graphical client. If you do run it in the background, keep track of its process and stop that exact process when finished. Avoid broad commands such as pkill xkbwatch on a shared machine, because another user may be running a separate observation session.

5. Separate watcher errors from XKB problems

A failure to open the display happens before xkbwatch can observe keyboard state. First resolve the connection to the X server. Only then should you investigate whether a layout switch or modifier event produces the state update you expect.

The manpage lists the standard X Toolkit command-line options as supported in addition to -version. Their exact syntax and behaviour come from the X Toolkit, not from an xkbwatch-specific setting. Use the documentation for the X Toolkit options available on your system rather than assuming that a generic option changes XKB state. xkbwatch itself is an observer, not a layout-management command.

Do not run it with sudo as a first response to a display error. Elevating the process can change which environment and authorisation credentials it sees, while granting it more access than an observation window needs. Use the ordinary session user and fix the display boundary instead.