Turn Linux Paths into GRUB Paths with grub-mkrelpath

GRUB and Linux do not always agree on how a path should look, and grub-mkrelpath converts one into the other. It never touches the filesystem it describes. The installed command is from grub-common 2.12-1ubuntu7.3. Allow about ten minutes for a one-off conversion, longer if you are wiring it into a script.

• Needs: a shell and a readable path that already exists.
• Runs as: an ordinary user. Do not reach for sudo by default; elevated privileges can make a path look readable without fixing the permissions your real boot or deployment process will use.

1. Check the installed command

Confirm which executable will run and record its version:

$ command -v grub-mkrelpath
/usr/bin/grub-mkrelpath
$ grub-mkrelpath --version
grub-mkrelpath (GRUB) 2.12-1ubuntu7.3

This is a path conversion utility, not a bootloader installer. It takes one positional argument, PATH, and otherwise only knows --help, --usage and --version.

2. Convert a known existing path

Pass the path as one argument. The command resolves it to a canonical path and prints the result:

$ grub-mkrelpath /usr/../usr/bin
/usr/bin
$ grub-mkrelpath /etc/passwd
/etc/passwd

These look familiar because the canonical path is already rooted at /, once the redundant .. component is stripped. The command also resolves symlinks while canonicalising, so the result names the real target rather than preserving whatever alias you typed.

GRUB treats the filesystem root specially. On this installed version, converting / itself produces an empty line:

$ grub-mkrelpath /
$

3. Use the output safely in a script

Capture standard output and check the exit status separately, so a diagnostic on standard error never gets mistaken for a converted path:

path='/usr/bin'
if relpath=$(grub-mkrelpath "$path"); then
    printf 'GRUB path: %s\n' "$relpath"
else
    status=$?
    printf 'Cannot canonicalise %s (status %s)\n' "$path" "$status" >&2
    exit "$status"
fi

Expected output for the example:

GRUB path: /usr/bin

Quote the input. A path with spaces needs to stay one argument, and quoting also stops the shell expanding wildcard characters before the command ever sees them. Never treat the command's error text itself as a success signal.

4. Check the input exists before converting it

Canonicalisation needs a real path, so a missing one fails cleanly rather than inventing an answer:

$ grub-mkrelpath /path/to/a-file-that-does-not-exist
grub-mkrelpath: error: failed to get canonical path of `/path/to/a-file-that-does-not-exist'.
$ printf '%s\n' "$?"
1

Check a placeholder path before converting it:

input='/path/to/a-file-that-does-not-exist'
if test -e "$input"; then
    grub-mkrelpath "$input"
else
    printf 'Not found: %s\n' "$input" >&2
    exit 1
fi

test -e follows symlinks, but it does not prove every component along the path is searchable by the current user. Let the conversion command have the final say and handle its non-zero status.

5. Keep conversion separate from boot changes

The command prints a name. It does not write a configuration file, install GRUB, copy a kernel, or restart anything:

$ grub-mkrelpath /boot
/boot
$ grub-mkrelpath /boot/grub
/boot/grub

Running those does not, by itself, make a boot path safer or more correct. If you later put the result into a GRUB configuration or deployment script, review that change on its own terms: bootloader edits can make a system unbootable, so take a tested backup and follow your distribution's recovery procedure first. Do not poke around directly under /boot just to see what happens.

$ grub-mkrelpath /boot/grub > /tmp/grub-path.txt
$ test -s /tmp/grub-path.txt && sed -n '1p' /tmp/grub-path.txt
/boot/grub

If you do overwrite the wrong file, stop before running any bootloader command and restore from your known-good backup. There is no undo inside grub-mkrelpath itself.

Common traps

• No argument. The command prints a usage diagnostic and exits non-zero; it needs exactly one path.
• Missing path. A canonicalisation error means the input cannot be resolved. Check spelling, mounts and permissions.
• Unexpected spelling. A relative path like . resolves to its canonical absolute form, so .. segments or symlinks can produce different text from what you typed.
• Blank output. For the filesystem root, an empty line is the correct converted result. Check the exit status, not whether the line has characters.
• Option confusion. --help, --usage and --version describe the tool, they do not convert anything. Put the path after any options.

For a final smoke test, convert a path you know and assert success:

$ result=$(grub-mkrelpath /usr/bin) && test "$result" = /usr/bin
$ printf '%s\n' "$?"
0