vinceliuice/grub2-themes: installing a GRUB boot menu theme

What grub2-themes replaces, and who it is for

A stock GRUB menu is a black screen with white text and a list of kernels. Changing it by hand means writing a theme.txt, positioning every component, supplying PF2 fonts at the right sizes, and wiring GRUB_THEME into /etc/default/grub. That is a few hours of work the first time and easy to get subtly wrong.

This project packages four theme families (tela, vimix, stylish, whitesur) with their icons, backgrounds and fonts, and ships an installer that assembles the right variant for your display. The audience is a desktop Linux user who already boots with GRUB and wants the menu to match the rest of the system. It is not a boot manager, not a kernel selector and not a replacement for GRUB itself; it only changes what GRUB draws.

The repository is Shell, licensed GPL-3.0, and the last push was on 2026-09-01. Releases are infrequent rather than continuous: 2024-08-19, 2025-03-03 and 2025-07-23. Treat it as a small tool that gets updated when themes or resolutions change, not as a project with a fast-moving roadmap.

How the installer turns options into a GRUB theme

install.sh is the whole mechanism. It takes a theme variant, an icon variant and a screen variant, then copies the matching files out of assets/, backgrounds/, config/ and common/ into a generated theme directory. The screen option selects which background and which font sizes are used, which is why the resolution has to be declared rather than detected: GRUB renders before any display server exists, so nothing can ask the monitor what it supports.

Fonts are the part most people miss. GRUB does not read TrueType files at boot. It reads PF2, a bitmap format produced by rasterizing a font at a specific size, so a theme that uses three text sizes needs three converted files. The bundled themes use DejaVu Sans from common/DejaVuSans.ttf, with Unifont included for Unicode coverage. common/makefont.sh regenerates those PF2 files and accepts either grub-mkfont or grub2-mkfont, covering the naming split between distributions such as NixOS on one side and Fedora and openSUSE on the other.

Icons follow a similar generation path. The contributing notes say that after changing or adding an icon you delete the existing one and run cd assets; ./render-all.sh, which implies the icon set is produced from source assets rather than edited in place.

Installing grub2-themes and applying a first theme

Clone the repository, then run the installer with sudo. With no options it opens a dialog interface instead of taking flags, which is the friendlier path if you do not remember the variant names.

git clone https://github.com/vinceliuice/grub2-themes.git
cd grub2-themes
sudo ./install.sh

For a scripted install, pass the theme, screen and icon variants explicitly. The README gives this example for a 2k display, and the defaults are tela, color and 1080p when a flag is omitted.

sudo ./install.sh -t tela -s 2k

If your resolution is not one of the presets, the custom-resolution flag takes an explicit size. The README shows 1600x900.

sudo ./install.sh -t tela -c 1600x900

On a system where the GRUB directory is /boot/grub or /boot/grub2 and you want the theme written there directly, the boot flag does that. The README example is:

sudo ./install.sh -b -t tela

Removal is the same script with -r and a theme name, and the name is required: the README states the theme option must be added and defaults to tela.

sudo ./install.sh -r -t tela

After any of these, the change is not live until GRUB regenerates its configuration. The README's own troubleshooting section gives the command for that step:

grub-mkconfig -o /boot/grub/grub.cfg

On NixOS the script is not the intended route. The repository ships flake.nix with a nixosModules.default, and the README walks through adding grub2-themes as a flake input and then enabling it in configuration.nix with boot.loader.grub2-theme. The module exposes enable, theme, footer and an optional customResolution, so the theme becomes part of the system configuration rather than a file the installer drops on disk.

Where grub2-themes breaks or is the wrong tool

The failure mode that matters is a boot menu you cannot read. GRUB picks a graphics mode before the operating system is running, and if GRUB_GFXMODE does not match what the firmware offers, you get a low-resolution menu, a garbled one, or in the worst case no usable display. The README addresses this directly: press c at the GRUB screen, run vbeinfo or videoinfo to list the modes the firmware reports, then edit GRUB_GFXMODE in /etc/default/grub to the height x width x 32 value that matches, and regenerate the config. That sequence is the fix, and it assumes you can still reach the GRUB command line.

Custom backgrounds have their own constraint. The README requires imagemagick, or at least something providing convert or magick, and the image must sit in the project root named background.jpg at the resolution matching the screen option you pass. A mismatched image is not resized for you; it is stretched or cropped by GRUB.

Two cases make this the wrong choice. If you boot with systemd-boot or rEFInd, this project has nothing for you, because it only produces GRUB themes. And if you are managing a fleet of machines where a broken boot menu means physical recovery, the cost of a cosmetic change is high relative to the benefit, and the installer's sudo requirement and config regeneration mean it is not a passive change.

What you would use instead, and how it differs

The direct alternative is writing the GRUB theme yourself. GRUB's theme format is documented, and the README links two external references, a Grub2 theme reference and a Grub2 theme tutorial on the ROSA wiki. Building your own gives you exact control over layout, fonts and colors, and no third-party script runs as root on your machine. The cost is that you handle PF2 conversion through grub-mkfont yourself and maintain the theme across GRUB updates.

A second alternative is a distribution package. Some distributions ship GRUB theme packages, which means updates arrive through the package manager and the files live in system paths rather than in a cloned directory. The trade-off is selection: a distribution package gives you whatever themes that distribution chose, while this project gives you four families with icon and resolution variants and a custom-resolution option.

The narrower alternative, if you only want a different boot experience rather than a different look, is switching bootloaders to systemd-boot or rEFInd. That changes the whole boot path and is a much larger decision than theming; it is worth naming only so you do not reach for this project expecting it to apply there.

Licence, maintenance and upgrade cost

The project is GPL-3.0. In practice that matters if you redistribute a modified theme or bundle the installer into something you ship; the licence text is in the repository as LICENSE, and this is not legal advice about your specific use.

Upgrades are manual. There is no package manager tracking this checkout, so updating means pulling the repository and re-running the installer, then regenerating the GRUB configuration. The bundled fonts are generated artifacts, so if you have customized fonts through common/makefont.sh, a pull can overwrite that work unless you re-run the script with your own font path and sizes. The same applies to a custom background.jpg placed in the project root: it lives inside the clone.

Release cadence is slow. Three releases appear in the record since August 2024, with the last push on 2026-09-01. Slow is not automatically bad for a theming tool, since GRUB's theme format is stable and the project mostly tracks new theme variants and resolution options. It does mean you should not expect quick fixes for a new distribution's font tool naming or a firmware quirk. If you need a change, the contributing notes point at the issue tracker and at the render-all.sh step for icon work.

Editorial conclusion

Adopt it if you run GRUB on a desktop and want a themed boot menu without hand-writing theme.txt files; the installer handles resolution, icons and fonts, and the NixOS module means a flake-based system can declare the theme instead of running the script. Skip it if your machine boots through systemd-boot or rEFInd, since nothing here touches those loaders, and skip it if you cannot test a bootloader change before relying on the machine. Before running install.sh, record the current contents of /etc/default/grub and confirm GRUB_GFXMODE matches your display, because a wrong mode is the failure you will actually see on reboot.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. vinceliuice/grub2-themes on GitHub