showkey watches the Linux keyboard layer fire keycodes, scan codes and mapped characters as you type, without changing a thing. This guide covers the default keycode view, raw-looking scan codes and the character values produced by the active keymap. It uses showkey from kbd 2.6.4, installed here as package version 2.6.4-2ubuntu2.
Allow about ten minutes. You need a physical or virtual Linux console, the showkey command and a keyboard you can test. A graphical terminal emulator is usually the wrong place: it receives terminal input after the desktop stack has processed it, while showkey reads keyboard events from the console input layer. No example changes a keymap, firmware, boot setting or service.
Safety boundary: These commands can reveal what you type, including keys used in secrets. Do not enter passwords, recovery codes or private messages while a dump is running. Stop it before returning to normal work.
Start with ordinary, non-privileged checks. They do not read keyboard events or change state:
$ command -v showkey
/usr/bin/showkey
$ showkey --version
showkey from kbd 2.6.4
$ showkey --help
Usage: showkey [option...]The exact help text can vary between kbd releases. On this installation, the help output also advertises --timeout and its short form -t, with a default of 10 seconds. The installed manpage describes the three dump modes and the same ten-second inactivity timeout, but does not list -t. Treat the executable's help as the authority for that version when you need to change the timeout.
Checkpoint: If command -v finds nothing, install the distribution's kbd package through its normal package-management process. Do not download an unrelated keyboard utility under the same name.
Switch to a Linux virtual console before running the interactive command. On many systems, Ctrl+Alt+F3 selects one, but the available console keys depend on the host. Log in there, then run the default mode:
$ showkey --keycodes
kb mode was ?UNKNOWN?
press any key (program terminates 10s after last keypress)...
keycode 30 release
keycode 30 pressThe headings and event order are illustrative. Your terminal may report a release before a press if a key was already held when the program started, and the keycode depends on the keymap and kernel. Press a single harmless key, observe its press and release events, then stop touching the keyboard and let the ten-second inactivity timeout end the program.
--keycodes is the explicit form of the default. With no option, the installed manpage says that showkey uses keycode dump mode. A keycode is the kernel's number for a physical key after lower-level scan-code handling. It is the useful mode for finding the number to place in a custom keymap, but it is not the same thing as a character such as a.
To stop sooner, send the process a suitable signal from another console, for example with kill. That needs the process ID and, if the process belongs to another user, may need elevated privileges. There is no state to undo because this mode only observes events.
Use scan-code mode when you are investigating a key that has no useful keycode mapping:
$ showkey --scancodes
kb mode was ?UNKNOWN?
press any key (program terminates 10s after last keypress)...
0x1e 0x9eThe output is hexadecimal bytes. showkey starts a new line after roughly 0.1 seconds without another byte, or when its receive buffer fills. A press and release can therefore appear as a short sequence, but the exact bytes depend on the keyboard, kernel and console path. Do not use this output as a guaranteed description of the electrical protocol emitted by the hardware.
Modern kernels may translate keycodes and then translate them back when this mode is requested. The installed manpage explicitly warns that the result is not necessarily the bytes sent by the keyboard hardware. If you need a low-level driver investigation, record the kernel version, keyboard connection and test conditions rather than treating one dump as universal.
A previously unmapped extra key may produce scan codes without a useful keycode. After identifying such a sequence, setkeycodes is the separate tool named by the manpage for assigning a keycode. That is a configuration change, so do not run it from this guide without first recording the existing mapping and planning how to restore it.
ASCII mode reports decimal, octal and hexadecimal values for the key according to the current keymap:
$ showkey --ascii
kb mode was ?UNKNOWN?
press any key (program terminates 10s after last keypress)...
keycode 30 press
a 97 0141 0x61The labels and spacing are representative rather than a fixed output contract. Shift state, Caps Lock, layout selection and dead-key behaviour can change the value. This mode is about the mapped character value, not an audit of the key's physical identity.
ASCII mode has a different stopping rule: the manpage says it ends when you type Ctrl+D. That control character may also be meaningful to a shell, so use it only while showkey has the console input. If you miss it, stop entering input and wait for the command's behaviour on your installed version, or terminate it from another console.
The installed program advertises -t and --timeout. Use a short value when you are collecting one quick sample:
$ showkey --keycodes --timeout 3
kb mode was ?UNKNOWN?
press any key (program terminates 3s after last keypress)...The value is a timeout in seconds on this kbd release. The command still waits for key activity, then exits after the chosen interval since the last event. If your system rejects the option, run showkey --help and follow that installed build's syntax; do not assume a newer option exists in an older package.
Do not redirect a dump into a file that contains secrets or shared account data. If you need a temporary capture for a non-sensitive key, use a deliberately named file in a private directory, inspect it, and remove it afterwards:
$ umask 077
$ showkey --scancodes --timeout 3 > /tmp/showkey-sample.txt
$ sed -n '1,20p' /tmp/showkey-sample.txt
$ rm -- /tmp/showkey-sample.txtThe final command is destructive for that temporary sample. Check the path before running it, and skip the capture entirely if the events could contain sensitive input. No sudo is required for the examples above; if your console permissions prevent access, diagnose the local console setup rather than granting broad privileges automatically.
If the command immediately complains that it cannot access a console or input device, check where you are running it and whether the session is a real Linux virtual console. A pseudo-terminal, SSH session or graphical terminal may not expose the event stream that showkey expects. Test from a local virtual console or from the host's supported console mechanism.
If output is empty, press and release one ordinary key and wait. If it still remains empty, check that the command has not already timed out and that the keyboard is attached to the machine whose console you are viewing. Do not infer a broken keyboard from an SSH terminal test.
If the key appears in scan-code mode but not in a useful keycode mode, that is evidence about the mapping layers, not permission to edit the keymap immediately. Record the exact scan-code output, layout, kernel version and kbd version first. Restore any mapping change from a known backup rather than guessing a replacement number.
--timeout option before changing it.