Map scancodes to keycodes

This page assumes that you have read Keyboard input, which provides wider context.

Mapping scancodes to keycodes is achieved in a layer lower than Xorg and Linux console, which means that changes to this mapping will be effective in both. [1][2][3] Note that this method can only be used for simple 1:1 key remaps; see Input remap utilities for programs which allow more complex remaps at the same low level.

There are two ways of mapping scancodes to keycodes:

Using udev
Using setkeycodes(8)

The preferred method is to use udev because it uses hardware information (which is a quite reliable source) to choose the keyboard model in a database. It means that if your keyboard model has been found in the database, your keys are recognized out of the box.

Identifying scancodes

You need to know the scancodes of keys you wish to remap. See Keyboard input#Identifying scancodes for details.

Using udev

You can use udev's hardware database to override the default scancodes-to-keycodes mapping by following udev#Remap specific device and the update/reload sections after.

Using setkeycodes

setkeycodes is a tool to load scancodes-to-keycodes mapping table into Linux kernel. It is best to use it with showkey. See Keyboard input#Using showkey and Keyboard input#Identifying keycodes in console.

Do note that setkeycodes only accepts xx and e0xx formatted hexadecimal scancodes, therefore you must omit the leading 0x portion of the scancodes given by showkey.

setkeycodes usage is:

# setkeycodes scancode keycode ...

It is possible to specify multiple pairs at once. Scancodes are given in hexadecimal, keycodes in decimal.

If using this simple command, changes will be lost after reboot. The changes can be made permanent by creating a new service:

/etc/systemd/system/setkeycodes.service

[Unit]
Description=Change keycodes at boot

[Service]
Type=oneshot
ExecStart=/usr/bin/setkeycodes [scancode] [keycode] [scancode] [keycode] [...]

[Install]
WantedBy=multi-user.target

and enabling setkeycodes.service.