Set NumLock and Other VT LEDs with setleds

NumLock refusing to stick on a bare console is a classic setleds moment, and the fix takes minutes once you know the flags. You will finish with a controlled way to inspect or change NumLock, CapsLock and ScrollLock on a Linux virtual terminal (VT). The examples use the installed setleds from kbd 2.6.4-2ubuntu2. Allow about ten minutes. You need a shell running on a Linux VT, or permission to open the target VT device.

Scope: setleds changes keyboard flag state for a VT. It is not a general desktop keyboard-settings tool. A graphical terminal emulator normally does not provide the VT ioctl this command needs.

1. Confirm the installed command

First check which executable your shell will run and record the package version. These are ordinary, read-only commands:

$ command -v setleds
/usr/bin/setleds
$ dpkg-query -W -f='${Package} ${Version}\n' kbd
kbd 2.6.4-2ubuntu2

The local manual documents the syntax as setleds [-v] [-L] [-D] [-F] [{+|-}num] [{+|-}caps] [{+|-}scroll]. Do not add undocumented long options to a script based on this guide.

Checkpoint: if command -v prints nothing, install or repair the kbd package through your normal system-management process. Do not work around that by downloading a random copy of the program.

2. Read the current flags on the active VT

Run setleds without arguments from a real virtual terminal. It reports the current flag settings and does not request a new setting:

$ setleds
$ printf 'exit status: %s\n' "$?"
exit status: 0

The exact status line format is implementation output, so treat the command's own report as authoritative. The flags are specific to the VT connected to standard input. From a graphical terminal, a shell, or a non-terminal pipe, the installed program can fail with an ioctl error such as Inappropriate ioctl for device, and a status such as 71.

Add -v to see the state before and after a later change. The manual says this reports both settings; it does not make the operation safe for a non-VT input.

3. Set or clear one flag for this VT

Use a plus sign to set a flag and a minus sign to clear it. This requests NumLock on the VT attached to standard input:

$ setleds +num
$ printf 'exit status: %s\n' "$?"
exit status: 0

Verify the resulting state by asking the command to report it:

$ setleds -v
# output varies with the terminal and current flags

Use the same form for the other flags:

$ setleds -caps
$ setleds +scroll

4. Target a named VT carefully

Standard input selects the VT, so shell redirection can target a device such as /dev/tty1:

$ sudo setleds -v +num < /dev/tty1

This may need elevated privileges because the device permissions belong to the console session. Use sudo only when the device denies access, and inspect the exact device path before running the command. The command changes that VT's flags, not the keyboard state of every terminal.

Checkpoint: run the same read-only query against the same device:

$ sudo setleds -v < /dev/tty1
# output varies; check the reported NumLock, CapsLock and ScrollLock values

Do not loop over /dev/tty* as a first test. It can change several users' consoles at once, and device names can include terminals that are not currently in use.

5. Choose temporary or default state

With no mode option, setleds changes the current VT flags. -F makes that choice explicit: change only the VT flags, whose state may be reflected by the keyboard LEDs.

-D changes both the current flags and their default settings, so a later reset will not undo the change. For example:

$ sudo setleds -D +num < /dev/tty1

This is a persistent behaviour change for that VT's defaults, so do not use -D merely to test whether NumLock works. For a one-off change, use +num without -D.

The manual does not provide a complementary command that restores the previous default automatically. Before using -D, record the current report with setleds -v. To undo the example above, clear NumLock in the default state with:

$ sudo setleds -D -num < /dev/tty1

Recovery: that undo assumes the earlier command was the only default-state change. If another administrator or startup script owns the setting, restore its documented value instead of guessing.

6. Keep LED-only mode separate

The -L mode changes the physical keyboard LEDs without changing the VT flags. Afterward, the LEDs no longer have to reflect those flags, which can make the light disagree with what NumLock, CapsLock or ScrollLock actually does. Reserve it for hardware or diagnostic cases where that separation is intentional.

$ sudo setleds -L +num < /dev/tty1

To restore the normal relationship in which the LEDs reflect the VT flags, run setleds -L without another flag:

$ sudo setleds -L < /dev/tty1
$ sudo setleds -v < /dev/tty1

This restores LED following; it does not mean every flag has been reset to a preferred value. Check the report after the operation.

7. Diagnose failures without guessing

An ioctl error usually means standard input is not a Linux VT. Move to a text console, commonly with a system-specific virtual-terminal switch, and run the command there. If you deliberately target a device, check it before using privilege:

$ test -c /dev/tty1 && echo 'character device exists'
character device exists
$ ls -l /dev/tty1

If the command succeeds but a key behaves unexpectedly, remember what the flags actually control: NumLock influences keypad interpretation, CapsLock complements Shift for letters, and ScrollLock controls console output behaviour. In keyboard application mode, the manual records a real limitation: the NumLock key does not influence the NumLock flag setting.

Do not troubleshoot a graphical desktop by repeatedly changing VT flags. Identify whether the input is a real VT first, then inspect the desktop environment's own keyboard settings if the application is not using the console keyboard path.

Done means