Build a GRUB PF2 Font from a TrueType File

GRUB cannot read your desktop fonts directly, so grub-mkfont converts a TrueType or OpenType file into the PF2 bitmap format it actually loads. This guide converts one, then verifies it before it goes anywhere near a boot configuration.

The examples use grub-mkfont from GRUB 2.12-1ubuntu7.3 in the grub-common package. Allow about ten minutes if the source font is already installed. You need a readable font file and a writable working directory; nothing in the conversion stage needs elevated privileges, and conversion never touches GRUB, the boot loader or the source font. Keep the source file until the PF2 output has been checked.

1. Check the installed command and source font

Confirm the version and pick a real font path. This guide uses a font present on the reference system:

$ grub-mkfont --version
grub-mkfont (GRUB) 2.12-1ubuntu7.3
$ test -r /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf && echo 'source font is readable'
source font is readable

Swap in the font you actually want to convert. grub-mkfont accepts common font formats but will not go searching font directories for you, so fix a missing path, unreadable file or unsupported format before you even look at options.

FONT='/path/to/your-font.ttf'
test -r "$FONT"

2. Create a basic PF2 file

Pass one input font, an output path, and a point size. The output option is required; there is no implicit output file:

$ grub-mkfont --size=16     --output=/tmp/grub-font.pf2     /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf

A successful command normally prints nothing and returns status 0, so verify status and file type instead:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ ls -lh /tmp/grub-font.pf2
-rw------- 1 ... ... 69K ...
$ file /tmp/grub-font.pf2
/tmp/grub-font.pf2: GRUB2 font "Liberation Sans Regular 16"

Exact size, ownership and timestamp vary. What actually matters is a zero exit status, a non-empty output, and a file description naming a GRUB2 font. The underlying PF2 file opens with the PFF2 format marker, which lines up with the official GRUB format documentation.

3. Choose the size and character range deliberately

--size sets the generated font size. Use a value that fits the display and theme you are building: a larger size inflates the file and can make a GRUB menu harder to use on a small screen, so do not pick one just because it looks good in a desktop application.

If the menu needs a specific character subset, use --range with one or more FROM-TO ranges separated by commas:

$ grub-mkfont --size=16     --range=0x20-0x7e,0xa3-0xa3     --output=/tmp/grub-font-latin.pf2     /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf

That example requests printable ASCII plus the pound sign. Treat the range syntax as an input contract: follow the format your installed command's help shows, and test the actual glyphs your menu uses. If a character is missing, GRUB simply cannot display it from that PF2 file.

For a font with several faces, --index picks one. --bold asks the converter for a bold result, while --no-hinting, --force-autohint and --no-bitmap change how the source is interpreted. Start with the defaults, then add one option at a time so a visual or compatibility problem has an obvious cause.

4. Set metadata only when the theme needs it

The generated file can carry a family name and an explicit ascent or descent. Use --name when the source metadata does not suit the theme, and touch --asce or --desc only when you have a measured layout problem, because changing metrics can shift vertical alignment:

$ grub-mkfont --size=16     --name='Boot Menu Sans'     --output=/tmp/grub-font-named.pf2     /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf
$ file /tmp/grub-font-named.pf2
/tmp/grub-font-named.pf2: GRUB2 font "Boot Menu Sans Regular 16"

Names and metrics describe the output, they do not install it or make GRUB select it. If you are troubleshooting a theme, keep a known-good PF2 file and change one conversion setting at a time before comparing screenshots.

5. Install the verified file only after conversion

GRUB loads fonts in PF2 format; the GNU manual documents the standard .pf2 extension and the loadfont command, but a theme or configuration still has to point at where your GRUB installation can read the file. That directory depends on the distribution and boot layout, so inspect your existing GRUB files before copying anything:

$ find /boot/grub -maxdepth 2 -type f -name '*.pf2' -print
$ grep -R 'loadfont|font:' /etc/default/grub /etc/grub.d /boot/grub 2>/dev/null

Reading those paths is ordinary user work, though some files may be unreadable without permission. Never assume /boot/grub/fonts exists or that a copied file gets picked up automatically.

$ sudo install -D -m 0644 /tmp/grub-font.pf2 /boot/grub/fonts/grub-font.pf2

That command only touches the named destination, but the destination directory and matching GRUB configuration still need to fit your system. Recovery: to undo it, remove the newly installed file only after confirming it is the one you created:

$ sudo rm -- /boot/grub/fonts/grub-font.pf2

Do not remove an existing distribution font as a shortcut. If you changed a theme or GRUB configuration too, restore its saved copy before regenerating configuration. A font conversion alone never requires grub-mkconfig.

6. Diagnose failures without guessing

If the command says --output is missing, add it explicitly. If it cannot open the input, check the path and read permission:

$ ls -l -- /path/to/your-font.ttf
$ test -r /path/to/your-font.ttf && echo readable

If the output already exists, use a different temporary name while testing rather than overwriting a file a working theme depends on. If the result looks wrong, compare a default-settings conversion against one changed setting at a time. Use --verbose for extra conversion messages, and --help to confirm option spelling for your installed GRUB version.

Do not run the converter as root merely because the source font lives under /usr/share/fonts. Read access is enough; save the privileged command for the final write into a protected boot directory, and stop if the destination path is not the one you intended.