Turn a Linux Console Keymap into a GRUB Keyboard Layout

You will finish with a GRUB keyboard layout file generated from a Linux console keymap, plus checks that show whether the conversion produced a usable file. The installed command is grub-mklayout from GRUB 2.12 package version 2.12-1ubuntu7.3.

Allow about fifteen minutes. You need a shell, a readable keymap description, and enough free space to write a new output file. The examples do not require root and do not alter GRUB configuration, the boot loader, or an existing keymap. Keep the generated file in a work directory until you have decided how your boot configuration will use it.

1. Check the installed contract

Start with read-only checks. This confirms which executable is first in your PATH and records the package version:

$ command -v grub-mklayout
/usr/bin/grub-mklayout
$ grub-mklayout --version
grub-mklayout (GRUB) 2.12-1ubuntu7.3
$ dpkg-query -W -f='${Package} ${Version}\n' grub-common
grub-common 2.12-1ubuntu7.3

Your version may differ. This guide follows the option names in the installed GRUB 2.12 manual, not an assumption that another distribution has identical packaging.

2. Prepare the input as a console keymap

grub-mklayout reads a Linux console keymap description and writes a format consumed by GRUB's keymap command. Its input and output defaults are standard input and standard output. In practice, a source generated by a keyboard-layout tool such as ckbcomp is the useful starting point; the converter expects lines such as keycode 30 = U+0061 U+0041 U+0061 U+0041.

The four values on that example line represent the unshifted, shifted, AltGr and shifted-AltGr actions for the Linux key number 30. The U+ form is explicit Unicode notation, which avoids depending on how a symbolic key name is interpreted. A minimal test input is safe to create in a temporary work directory:

$ work=$(mktemp -d /tmp/grub-mklayout.XXXXXX)
$ printf '%s\n' 'keycode 30 = U+0061 U+0041 U+0061 U+0041' > "$work/test.map"
$ sed -n '1p' "$work/test.map"
keycode 30 = U+0061 U+0041 U+0061 U+0041

For a real layout, use your existing keymap source rather than replacing it with this one-line test. The keymaps manual describes comments, include lines and key definitions, but not every Linux key action has a useful GRUB equivalent. Treat warnings about an unknown scan identifier as a conversion problem to investigate, not as proof that the resulting file is complete.

3. Convert to a named output file

Use explicit paths for both sides of the conversion. This is an ordinary user-level command:

$ grub-mklayout --input "$work/test.map" --output "$work/test.gkb"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file "$work/test.gkb"
test.gkb: data

The exact file description can vary because the output is a GRUB-specific binary layout. The useful checks are a zero exit status and a non-empty output file. Confirm its size directly:

$ test -s "$work/test.gkb" && echo 'output is non-empty'
output is non-empty
$ od -An -tx1 -N9 "$work/test.gkb"
 47 52 55 42 4c 41 59 4f 0a

The first bytes identify the generated GRUB layout as GRUBLAYO followed by a newline. Do not edit this file in a text editor: it is binary output, not a second keymap source.

Important: a zero exit status does not make an unrecognised input meaningful. The converter can write a layout while reporting unknown key symbols on standard error. Capture diagnostics when converting a real file:

$ grub-mklayout -i /path/to/layout.map -o "$work/layout.gkb" 2>"$work/grub-mklayout.err"
$ if test -s "$work/grub-mklayout.err"; then cat "$work/grub-mklayout.err"; else echo 'no diagnostics'; fi
no diagnostics

4. Use standard input and standard output deliberately

The same converter can be used in a pipeline. This is convenient for a generated keymap, but it makes it easier to lose diagnostics or overwrite a destination by accident:

$ printf '%s\n' 'keycode 30 = U+0061 U+0041 U+0061 U+0041' \
    | grub-mklayout > "$work/piped.gkb"
$ cmp "$work/test.gkb" "$work/piped.gkb" && echo 'named and piped output match'
named and piped output match

Redirection with > truncates an existing destination before the command runs. That is the main local data-loss trap in this workflow. Write to a new name, verify it, then replace an old layout only if you have a backup and a tested recovery path:

$ cp --preserve=all /path/to/current.gkb /path/to/current.gkb.bak
$ grub-mklayout -i /path/to/layout.map -o /path/to/current.gkb.new
$ test -s /path/to/current.gkb.new && mv /path/to/current.gkb.new /path/to/current.gkb

The last command is the state-changing step. If conversion fails, leave the backup and the old file in place. Do not remove the backup until the new layout has been tested in the boot workflow that consumes it.

5. Understand the options and boundaries

-i and --input select the source file. -o and --output select the binary destination. With neither option, the command reads standard input and writes standard output. -v or --verbose enables verbose messages; --help, --usage and --version only report information.

Changing a file under /boot or a GRUB configuration directory may require elevated privileges, but conversion itself does not. Do not add sudo until you have verified the output in a user-owned directory. If you later install the file into a boot configuration, make a backup first and ensure you know how to select the previous boot entry. A bad keyboard layout can make an otherwise healthy boot menu difficult to operate.