Turn a Console Keymap into a GRUB Layout

grub-mklayout converts a Linux console keymap into the binary format GRUB needs for a non-US layout. This guide finishes with a generated layout file plus checks that show whether the conversion actually produced something usable.

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 for a new output file. None of this needs root, and none of it alters 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: which executable is first in your PATH, and which package version you have:

$ 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 packages it identically.

2. Prepare the input as a console keymap

grub-mklayout reads a Linux console keymap description and writes a format GRUB's keymap command consumes, defaulting to standard input and standard output. In practice, output from a keyboard-layout tool such as ckbcomp is the useful starting point; the converter expects lines like keycode 30 = U+0061 U+0041 U+0061 U+0041.

Those four values are the unshifted, shifted, AltGr and shifted-AltGr actions for Linux key number 30. The U+ notation is explicit Unicode, which sidesteps how a symbolic key name might otherwise be interpreted. A minimal test input is safe to build in a scratch 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-liner. The keymaps manual describes comments, include lines and key definitions, but not every Linux key action has a useful GRUB equivalent. Treat a warning about an unknown scan identifier as a conversion problem to chase, not proof that the resulting file is complete.

3. Convert to a named output file

Use explicit paths on both sides. 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 since the output is a GRUB-specific binary layout. What matters is a zero exit status and a non-empty output file:

$ 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

Those first bytes spell out GRUBLAYO followed by a newline. Do not open this file in a text editor: it is binary output, not a second keymap source.

$ 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 works fine in a pipeline, which is convenient for a generated keymap but makes it easier to lose diagnostics or clobber 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 even runs. That is the main local data-loss trap in this whole workflow. Write to a new name, verify it, then replace an old layout only once 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

That last command is the state-changing step. If conversion fails, leave the backup and the old file exactly where they are. Do not remove the backup until the new layout has been tested in the boot workflow that will actually use it.

5. Understand the options and boundaries

• -i / --input selects the source file.
• -o / --output selects the binary destination. With neither, the command reads standard input and writes standard output.
• -v / --verbose enables verbose messages.
• --help, --usage, --version only report information and change nothing.

Changing a file under /boot or a GRUB configuration directory may need elevated privileges, but conversion itself never does. 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, back it up first and make sure you know how to pick the previous boot entry: a bad keyboard layout can make an otherwise healthy boot menu awkward to operate.