Home / Alt manpages / grub-mkdevicemap(8)

  • grub-mkdevicemap(8)
  • Admin command
  • linux

Generate a GRUB Device Map Without Guessing

A stale device map is the kind of thing nobody remembers exists until GRUB starts booting the wrong disk. grub-mkdevicemap builds the map between GRUB's BIOS-style drive names and your operating system device files, and this guide shows how to generate one into a chosen file, inspect what the probe found, and only then decide whether it belongs in /boot/grub/device.map.

The route

Jump straight to the step you need, or tick off Done means at the end.

Allow about 10 minutes. You need the grub-common package and a shell; writing the default file needs root.

What this command actually changes

A map entry has the general shape (hd0) /dev/sda. GRUB tools use this when a fixed device ordering matters, especially in an environment that differs from the machine's normal boot environment.

Modern GRUB configurations usually prefer filesystem UUIDs or labels, so a device map is not a general cure for a boot failure. If no map exists, GRUB utilities build a temporary one on the fly. Treat a persistent map as an explicit override: a stale disk order can be worse than having no file at all.

1. Check the installed version

This guide was checked with Ubuntu's grub-common package version 2.12-1ubuntu7.3. Confirm the command on the machine you are actually changing:

$ grub-mkdevicemap --version
grub-mkdevicemap (GRUB) 2.12-1ubuntu7.3

The version line can differ on another release. Confirm the executable comes from the expected package before you go further:

$ command -v grub-mkdevicemap; dpkg-query -W -f='${Package} ${Version}\n' grub-common

Checkpoint

You have a working command and know which GRUB package version you are about to use.

2. Generate a disposable map first

Do not start by writing the default path. Generate a temporary copy so you can inspect it without touching the boot configuration:

$ map_file=$(mktemp /tmp/grub-device-map.XXXXXX); grub-mkdevicemap --no-floppy --device-map="$map_file" --verbose; printf 'map: %s\n' "$map_file"; sed -n '1,80p' "$map_file"
  • --device-map selects the output file.
  • --no-floppy skips probing floppy drives. That avoids a needless delay or probe error on most current machines.
  • --verbose asks for diagnostic messages. A quiet run that exits successfully is still normal, and the file can even be empty if the environment exposes no mappable devices.

On a machine with a discoverable disk, the contents may look like this:

(hd0) /dev/sda
(hd1) /dev/sdb

That is an example of the file format, not output to copy blindly. Check the real device names with lsblk and compare them against the system's intended boot order. Never assume hd0 is the disk mounted at /.

Checkpoint

The generated file exists, and every mapping you plan to keep matches a real device and the firmware or virtual machine's disk order.

3. Decide whether a persistent map is needed

Keep the temporary result only if a GRUB tool or a virtual machine setup specifically needs a stable BIOS-to-device override. Otherwise, leave the system without a persistent map and use UUIDs or filesystem labels in custom GRUB entries.

Warning

Be especially cautious after adding, removing or reordering disks. Kernel device names like /dev/sda are not a permanent identity, and a map made before a hardware change can point GRUB at the wrong disk. If you are working on a remote or production machine, arrange console or recovery access before touching boot-related files.

4. Install the map at the default path only when justified

The manpage's default output is /boot/grub/device.map. Writing there changes system state and normally needs elevated privileges. Preserve any existing file first, then generate the new map:

$ sudo cp --preserve=mode,ownership /boot/grub/device.map /boot/grub/device.map.backup; sudo grub-mkdevicemap --no-floppy --device-map=/boot/grub/device.map --verbose

The backup command is expected to fail if no old map exists, and that is fine: continue with generation only after checking the message and confirming the destination is the file you meant. Never replace a map on a host whose disk order you have not checked.

To use a different location instead, keep the explicit option when invoking whichever GRUB tool consumes the map:

$ sudo grub-probe --device-map=/path/to/verified-device.map --target=drive /dev/sda1

The exact consumer may have additional requirements. grub-mkdevicemap itself only documents the map-generation options below; it does not install a boot loader or rewrite grub.cfg.

5. Verify the result and recover if it is wrong

Read the installed file and check its ownership and mode:

$ sudo sed -n '1,80p' /boot/grub/device.map; stat -c '%A %U:%G %n' /boot/grub/device.map

Every non-comment line should name a GRUB drive and an operating system device. If the map is wrong, restore the backup rather than editing a drive name from memory:

$ sudo cp --preserve=mode,ownership /boot/grub/device.map.backup /boot/grub/device.map

Recovery

If there was no previous map, remove the newly created file only after confirming no GRUB workflow depends on it, and let the utilities fall back to their temporary mapping. Removal here is a privileged, state-changing operation; if the machine no longer boots, use your distribution's normal recovery procedure instead of improvising.

Options that matter here

  • -n or --no-floppy skips floppy probing.
  • -s or --probe-second-floppy probes the second floppy drive. Use it only when that hardware is actually relevant.
  • -m FILE or --device-map=FILE selects the output path; the default is /boot/grub/device.map.
  • -v or --verbose requests verbose messages.
  • -h and -V print help or version information and exit.

Done means

  • Version checked. The installed version and package were confirmed.
  • Disposable run first. A test map was generated and inspected before anything live changed.
  • Mappings verified. Each retained mapping matches the intended disk order.
  • Backup taken. Any persistent change has a recoverable backup.
  • Need justified. You can explain why a map is needed rather than keeping one out of habit.