Inspect Linux Console Scancode Mappings with getkeycodes

Use getkeycodes to print the Linux kernel's current scancode-to-keycode table for the active virtual console. This is a read-only inspection: it does not change a keyboard mapping. The useful result is a table you can compare when diagnosing a key that works in one console but not another.

Allow about five minutes. You need the kbd package and a local Linux virtual terminal, such as /dev/tty1 through /dev/tty63. An SSH shell, terminal emulator, container, or graphical desktop terminal is not automatically a virtual console.

1. Check the installed command

Run the version check as your ordinary user. This command is harmless and does not need sudo.

getkeycodes --version

On the machine used for this guide, the installed output is:

getkeycodes from kbd 2.6.4

The package version is kbd 2.6.4-2ubuntu2 on that system. Your distribution may package a different release. The local manual page describes the basic command but says that it has no options; this installed 2.6.4 binary additionally accepts --version. Treat the output from your own binary as authoritative for that detail.

Checkpoint: the command is present

Continue when getkeycodes --version prints a kbd version. If the shell says that the command is not found, install the distribution package named kbd using your normal package-management process. Installing a package changes system state, so confirm the package name and repository before doing that on a production host.

2. Run the mapping query from a virtual console

Switch to a Linux virtual terminal with Ctrl+Alt+F3, or another function key provided by your system. Log in, then run:

getkeycodes

The command has no required arguments. Its output is a formatted table containing plain scancodes in hexadecimal and their keycodes in decimal, followed by the escaped e0 scancode range. The kernel supplies the values, so the exact numbers depend on the active console and kernel keyboard support.

For the ordinary low range, the kbd implementation explains that scancodes from 1 through 88 normally correspond to the same keycode. Later entries are queried from the kernel. A dash means that a queried entry was not available. Read the table as an observation of the console mapping, not as a translation table for X11, Wayland, USB HID usage codes, or an application-specific input library.

Checkpoint: record the table before changing anything

Save the output if you are comparing a working and failing console. Redirection is read-only with respect to the keyboard, but it creates or replaces the named output file, so choose a new path or an explicitly disposable file:

getkeycodes > /tmp/getkeycodes-before.txt
sed -n '1,12p' /tmp/getkeycodes-before.txt

Do not treat this file as a configuration file. Feeding it to another command will not restore a mapping. The related setkeycodes(8) command changes the kernel mapping and has a separate syntax and risk profile.

3. Handle the console error correctly

If you run the command from SSH or a graphical terminal, you may see:

Couldn't get a file descriptor referring to the console.

This means the program could not obtain a usable Linux console device in that session. It is not evidence that the keyboard has an empty mapping. Repeat the test from a local virtual terminal, or use an administrative recovery console that actually exposes one.

Running the same command with sudo can help only when permissions are the problem. It cannot turn an SSH pseudo-terminal or a container's standard input into a virtual console:

sudo getkeycodes

Use elevated privileges only when your system's device permissions require them. The command itself reads the mapping and does not need to modify files or restart a service. If it still reports the console error with sudo, stop retrying it in that session and move to a real virtual terminal.

4. Compare a suspicious key without changing the mapping

First capture the table on a console where the key behaves as expected. Then capture it on the console where it fails:

getkeycodes > /tmp/getkeycodes-working.txt
getkeycodes > /tmp/getkeycodes-failing.txt
diff -u /tmp/getkeycodes-working.txt /tmp/getkeycodes-failing.txt

If both captures are from the same kernel and console state, identical tables suggest that the fault is elsewhere. Check the program's input path, the desktop input stack, the keyboard layout, or the device's event stream. A changed table is evidence of different kernel console state, but it does not by itself identify which command or service caused the change.

Do not use setkeycodes as an experiment on a remote machine. It changes keyboard behaviour and can make recovery awkward if the key you need for switching consoles or logging in is affected. If you deliberately change a mapping later, record the original table first and keep a tested out-of-band access method.