grub2-themes: Tela, Vimix, Stylish and Whitesur, and the option that has no description

install.sh takes a theme, an icon set and a screen class in one command

The entire interface is one shell script run as root, and its whole option set is short enough to read in a single look:

  -t, --theme                 theme variant(s)          [tela|vimix|stylish|whitesur]       (default is tela)
  -i, --icon                  icon variant(s)           [color|white|whitesur]              (default is color)
  -s, --screen                screen display variant(s) [1080p|2k|4k|ultrawide|ultrawide2k] (default is 1080p)
  -c, --custom-resolution     set custom resolution     (e.g., 1600x900)                    (disabled in default)
  -r, --remove                remove theme              [tela|vimix|stylish|whitesur]       (must add theme name option, default is tela)
  -b, --boo

The first three flags choose what the boot screen looks like, the fourth overrides the resolution, the fifth takes a theme back off the system, and the sixth has no explanation at all. Running `sudo ./install.sh` with no flags at all does not install a default silently: it opens a dialog interface instead, so a bare invocation is interactive.

Tela is the default, and Whitesur appears in two lists at once

Four theme variants exist, tela, vimix, stylish and whitesur, and tela is what you get if you name no theme. Icon variants are a separate axis with three values, color, white and whitesur, where color is the default.

Whitesur sitting in both lists is worth pausing on. It is the one theme name that also appears as an icon variant.

The remove flag shares the theme axis and the same default, so an unqualified `-r` acts on tela specifically rather than on whatever you last installed.

-b is the one option with no description attached to it

Five of the six options come with a variant list, a default, or both. The sixth, `-b, --boo`, is listed with nothing after it. The only place its meaning appears is the comment on one example, which describes installing a theme into `/boot/grub/themes`:

sudo ./install.sh -b -t tela

So the documentation gives you the invocation and the destination, and leaves the flag itself unexplained. If you are deciding whether to pass it, the honest position is that the script is what defines the behaviour, not the option summary.

The practical consequence is small but real for anyone scripting installs across machines: with no description, no default and no stated conditions, there is nothing in the documentation to check your command against before you run it as root on a machine whose boot menu you depend on.

Five named screens cover five exact resolutions and nothing else

The screen axis is a closed list of five classes, and the project states the mapping from pixels to class name:

1920x1080 >> 1080p
2560x1080 >> ultrawide
2560x1440 >> 2k
3440x1440 >> ultrawide2k
3840x2160 >> 4k

Anything outside those five needs the custom resolution flag, which is marked disabled in default and takes a value such as 1600x900. A 1600x900 laptop, a 1920x1200 panel or a 2560x1600 screen all fall outside the list, so the honest choice for those machines is `-c` with an explicit size.

Backgrounds follow the same rule. A custom image must be named `background.jpg` and placed in the root of the project, and the installer wants imagemagick, or at least something providing `convert` or `magick`.

A resolution change is a two file edit plus a regenerated grub.cfg

When the display mode is wrong, the fix is not in the theme. On the GRUB screen you press `c` to reach the command line, run `vbeinfo` or `videoinfo` to see what the firmware offers, then open `/etc/default/grub` and edit `GRUB_GFXMODE=[height]x[width]x32` to match. Finally `grub-mkconfig -o /boot/grub/grub.cfg` rewrites the config so the change takes effect.

Three things follow from that sequence. The height comes before the width, which is the reverse of what most people type first. You need a rebuild after the edit. And the `x32` suffix is part of the value, not decoration.

install.sh also offers -c to set a custom resolution when it installs the theme.

Fonts are rasterized into PF2 once per size, and makefont.sh does it

GRUB themes use the PF2 font format, which means the source font has to be converted for every size the theme uses. The bundled themes use the DejaVu Sans files from `common/DejaVuSans.ttf`, and Unifont is included for broad Unicode coverage. To rebuild them:

cd common
./makefont.sh

The script accepts both command names Linux distributions ship, `grub-mkfont` including on NixOS and `grub2-mkfont` including on Fedora and openSUSE. Converting a different font takes a path, an output prefix and optional sizes:

./makefont.sh /path/to/MyFont.ttf my-font 16 24 32

The gap for anyone doing this themselves is that the sizes a given theme actually needs are not written down, so you either rebuild the bundled sizes or guess.

NixOS gets a declarative module instead of the root script

The NixOS path does not use install.sh at all. It asks you to enable flakes first, with a warning that flakes are still an unstable feature, and then to add the project as an input in `flake.nix`:

# flake.nix
{
  description = "NixOS configuration";
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    # Add grub2 themes to your inputs ...
    grub2-themes = {
      url = "github:vinceliuice/grub2-themes";
    };
  };
  outputs = inputs@{ nixpkgs,  grub2-themes, ... }: {
    nixosConfigurations = {
      my_host = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        specialArgs = { inherit inputs; };
        # ... and then to your modules
        modules = [
          ./configuration.nix
          grub2-themes.nixosModules.default
        ];

The theme is then set declaratively, with an enable flag, a theme name, a footer switch and an optional customResolution of `1600x900`.

Icon work goes through render-all.sh, and the repository keeps no changelog

If you change an icon or add one, the contribution path is prescribed: delete the existing icon if there is one, then run:

cd assets; ./render-all.sh

After that you open a pull request from your branch or fork, and problems go to the issue page. That is the whole contributor workflow, and it explains the small top level: LICENSE, README.md, assets/, backgrounds/, banner.png, common/, config/, flake.nix, install.sh and preview.png.

What is absent matters as much. There is no changelog file, no per theme documentation, and the releases are named by date alone, 2025-07-23, 2025-03-03 and 2024-08-19, so you cannot tell from the release what changed inside a theme. The project shows 4640 stars, 289 forks and 60 open issues, and the last push on the master branch is dated 2026-09-01.

Editorial conclusion

Fit this if you want a styled boot menu on a standard 1080p, 2k, 4k or ultrawide screen. Skip it if you need the option flags explained, because -b carries no description at all and the repository keeps no per theme documentation or changelog.

Frequently asked questions

Official sources

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