xkbvleds

xkbvleds [-display dpy] [-print] [-set state] [-sync] [-quiet] [-help]

-display name
    Connect to X server on display name.

-print
    Print current LED states (default action).

-set state
    Set LEDs to state: space-separated names (e.g., NumLock) or indices (e.g., 0). Prefix with - to turn off.

-sync
    Synchronize server after setting LEDs.

-quiet
    Suppress non-error messages.

-help
    Show usage summary.

xkbvleds is a lightweight command-line utility in the X Window System for inspecting and manipulating the state of keyboard indicator LEDs through the X Keyboard Extension (XKB).

It enables users to retrieve the current status of LEDs such as Num Lock, Caps Lock, and Scroll Lock, or programmatically set them on or off. This is particularly useful for shell scripts, automation tasks, or troubleshooting keyboard configurations in X11 environments.

By default, running xkbvleds without arguments prints the current LED states in a human-readable format, showing which LEDs are lit. The -print option explicitly triggers this behavior, while -set allows specifying a new state using LED names (e.g., NumLock CapsLock) or numeric indices (e.g., 0 1 for Num Lock and Caps Lock). Names must match those defined by the X server, typically NumLock, CapsLock, ScrollLock, Compose, or Kana.

The tool communicates directly with the X server, making it non-intrusive for console-only systems. Options like -sync ensure changes propagate reliably, and -quiet suppresses verbose output. It requires an XKB-capable server and does not persist changes across sessions or affect console LEDs.

Common use cases include resetting LED states after keymap changes or integrating into desktop startup scripts.

Requires X11 with XKB extension; no effect on Wayland or console. LED names/indices vary by server config. Changes are temporary.

Standard names: NumLock (0), CapsLock (1), ScrollLock (2), Compose (3).
To turn off: -NumLock or -0.

xkbvleds -print → Shows current states.
xkbvleds -set NumLock → Turns on Num Lock.
xkbvleds -set -CapsLock ScrollLock -sync → Off Caps, on Scroll, sync.

Developed as part of xkbutils with XKB extension in X11R6 (1994-1998). Maintained in xorg-xkb-utils; largely stable since inception.

xset(1), setxkbmap(1), xkbcomp(1)