Safely test and load a Linux console keymap with loadkeys

By the end, you will be able to check a keymap before applying it, save a rollback copy of the current console bindings, and load a replacement with a clear recovery path. This takes about 10 minutes if the keymap already exists. You need a real Linux virtual console, not an ordinary terminal emulator, and loadkeys from kbd 2.6.4 on the system used for this guide.

Understand the boundary first

loadkeys changes the kernel keyboard translation table for the console. The table is shared by all virtual consoles, so a change made on one console affects the others as well. It can also remain in effect at a login prompt after your shell exits. Anyone who can read /dev/console may be able to change the layout, so treat this as a privileged and security-sensitive operation.

The command does not configure an X11 or Wayland desktop keyboard. If the problem only appears in a graphical session, use that session's input configuration instead. Move to a text virtual console before testing a change, usually with Ctrl+Alt+F3, if your host provides one.

Checkpoint 1: confirm the installed command

Check the version without changing the keyboard:

$ loadkeys --version
loadkeys from kbd 2.6.4

The long form --version is the documented equivalent of -V. If the command is missing, install the kbd package using your distribution's normal package-management procedure. Do not copy a keymap from an unrelated distribution until you have checked its syntax and symbols.

Checkpoint 2: identify a keymap

loadkeys accepts one or more filenames. A name such as uk may resolve through the system's keymap search path, while an explicit path removes ambiguity. The format is documented by keymaps(5); the current bindings can be inspected with dumpkeys(1).

For a harmless first check, ask the installed program to parse a candidate without applying it:

$ loadkeys --parse /path/to/candidate.map

--parse searches for and parses the keymap without action. A successful run normally produces no output and returns status zero. Check that status explicitly when using it in a script:

$ loadkeys --parse /path/to/candidate.map
$ printf 'status=%s\n' "$?"
status=0

On this machine, parsing still needs access to the console device. An error such as Couldn't get a file descriptor referring to the console means the check was run from an unsuitable environment, such as a container or non-console session; it is not evidence that the keymap is valid.

Checkpoint 3: save a rollback copy

Before applying anything, save the current kernel keymap to a private temporary file. This is an ordinary read operation, but the output may describe local keyboard customisations, so keep its permissions restrictive:

$ umask 077
$ dumpkeys > /tmp/console-keymap.before
$ wc -l /tmp/console-keymap.before
123 /tmp/console-keymap.before

The exact line count will differ. A non-empty file is a useful checkpoint. If dumpkeys cannot access the console, stop here and do not apply a change from a different session. The saved file is only a rollback aid; keep it until you have verified the replacement.

Checkpoint 4: apply the keymap deliberately

This step changes the shared console state and normally requires elevated privileges. Run the parse check again immediately before loading, then apply the exact file you checked:

$ loadkeys --parse /path/to/candidate.map && sudo loadkeys /path/to/candidate.map

Do not use --unicode casually. It forces conversion to Unicode and may change a non-Unicode console while it runs. The manual recommends using kbd_mode(1) before loadkeys instead. In normal use, let loadkeys detect the console mode automatically.

If you are loading a named distribution keymap, the same boundary applies:

$ sudo loadkeys uk

Replace uk only with a keymap name or file that exists on your host. Keep another login method available. A bad mapping can make punctuation, the minus key, or the keys needed to type the recovery command unavailable.

Checkpoint 5: verify and recover

Test the affected keys on every virtual console you care about. Then inspect the active table:

$ dumpkeys | less

For compose-key changes, inspect only that part of the state:

$ dumpkeys --compose-only

A keymap containing compose definitions replaces the old compose definitions. A keymap without them leaves the existing accent table alone unless --clearcompose is supplied. Similarly, strings are added or replaced by default; --clearstrings is required when you need a defined empty string table. These defaults explain why loading a partial map may leave older behaviour behind.

If the result is wrong, restore the file made in Checkpoint 3:

$ sudo loadkeys /tmp/console-keymap.before

If that file is unavailable, sudo loadkeys --default requests the system default keymap, probably defkeymap.map from /usr/share/keymaps on this installation. That is a fallback, not an exact undo: it may discard deliberate local customisations.

Useful non-loading modes

Two options generate data instead of changing the current keymap. --mktable writes a kernel source table to standard output. --bkeymap writes a binary keymap suitable for BusyBox loadkmap. Redirect those outputs only after deciding where the file should go, because a terminal full of generated data is hard to inspect and easy to paste accidentally.

$ loadkeys --mktable > /tmp/defkeymap.c
$ loadkeys --bkeymap > /tmp/console.bmap

These commands do not modify the current keymap. Keep generated files in a controlled location and do not install them as system defaults until the consumer and format have been checked.

Done means

• loadkeys --version reports the installed kbd version.
• The candidate returns status zero with loadkeys --parse from a real console.
• dumpkeys produced a rollback copy before the change.
• The replacement was loaded with the intended privilege and keymap path.
• All affected virtual consoles behave as expected, or the saved map restored them.