Turn absolute Linux paths into GRUB paths with grub-mkrelpath

You will turn an existing Linux path into the root-relative form expected by GRUB, while keeping the original filesystem untouched. The installed command is from grub-common 2.12-1ubuntu7.3. Allow about ten minutes for a one-off conversion, or a little longer if you are adding it to a script.

You need a shell and a readable path that already exists. The examples only inspect names, so they normally run as an ordinary user. Do not use sudo by default. Elevated privileges can make a path appear readable without fixing the permissions your actual 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

The manual describes one positional argument, PATH. The useful options are --help, --usage and --version; this is a path conversion utility, not a bootloader installer.

Checkpoint: if command -v finds nothing, stop and install or repair the package through your normal distribution process. Do not copy a random binary into /usr/bin.

2. Convert a known existing path

Pass the path as one argument. The command resolves it to a canonical path and writes the converted result to standard output:

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

In these examples the output is still visually familiar because the canonical Linux path is already rooted at /. The command has removed the redundant .. component. It also resolves symlinks while canonicalising, so the result identifies the target path rather than preserving a spelling that may only be an alias.

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

$ grub-mkrelpath /
$

That empty output is a valid result for the root itself. Do not treat it as a failed command merely because there is no visible path after the prompt.

3. Use the output safely in a script

Capture standard output and test the exit status separately. This prevents a diagnostic on standard error from being 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 is:

GRUB path: /usr/bin

Quote the input. A path containing spaces must remain one argument, and quoting also prevents shell expansion of wildcard characters. Do not parse the command's error text as a success signal.

4. Check that the input exists before conversion

grub-mkrelpath needs to canonicalise the path. A missing path therefore fails rather than inventing a result:

$ 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 without changing anything:

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

Be aware that test -e follows links and does not by itself prove that every component is searchable by the current user. Let the conversion command remain the final authority 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 a service. A normal diagnostic workflow is therefore:

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

Those commands do not make the boot path safer or more correct by themselves. If you later place the result in a GRUB configuration or deployment script, review that separate change first. Bootloader edits can make a system unbootable, so take a tested backup and follow your distribution's documented recovery procedure before applying them. Do not experiment directly under /boot just to see what happens.

Likewise, do not redirect output over a file that matters. Redirection with > truncates its destination before the command completes. For a reviewable intermediate file, choose a new name:

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

The example writes only to /tmp. If you accidentally wrote the wrong output over a configuration file, stop before running a bootloader command and restore it from your known-good backup. There is no undo operation in grub-mkrelpath itself.

6. Diagnose the common traps

• No argument: the command prints a usage diagnostic and exits non-zero. Supply exactly one path.
• Missing path: the canonicalisation error means the input cannot be resolved. Check spelling, mounts and permissions.
• Unexpected spelling: a relative path such as . is resolved to its canonical absolute path. A path containing .. or symlinks may therefore produce different text from the input.
• Blank output: for the filesystem root, an empty line is the converted result. Check the exit status, not whether the line has characters.
• Option confusion: --help, --usage and --version describe the utility; they do not convert a path. Put the path after the options.

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

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