Minegrub: a Minecraft-style GRUB theme with a Python updater

What Minegrub actually solves

GRUB's default menu is a black screen with a list of kernels. Minegrub replaces that with a Minecraft main menu: a background image, a logo image that carries splash text, and buttons styled after the game. The repository also ships a second theme in the same family, a world selection menu, and a third project that combines the two.

The target user is someone running Linux with GRUB 2 who already edits /etc/default/grub without hesitation. The installation instructions assume root access, a boot partition you can write to, and a willingness to regenerate grub.cfg. Nothing here is packaged as a distro theme, so there is no apt install. You clone the repository and copy files into place.

The interesting part is not the artwork. It is update_theme.py, which regenerates the logo image at boot so the splash text changes, and rewrites the installed package count. That is what separates Minegrub from a static theme drop.

How the theme, the updater and the boot flow fit together

A GRUB theme is a directory containing theme.txt plus the images and fonts it references. Minegrub follows that layout: the minegrub/ directory holds theme.txt, a background image, generated logo images and an assets/ folder with splashes.txt. GRUB reads theme.txt at boot time through the GRUB_THEME variable in /etc/default/grub.

The dynamic behaviour comes from update_theme.py, which runs after boot, not during it. It picks a random line from assets/splashes.txt, renders a new logo.png with Pillow, counts installed packages using fastfetch or neofetch, and optionally copies a random image from backgrounds/ over background.png. Because it writes into the theme directory on the boot partition, the next boot shows the new splash and count.

Background selection has a detail worth knowing. Files whose names begin with a dot are ignored. Files prefixed with a version number also switch the button style: 1.15 and newer get a white outline with white text, older or unversioned images get the classic blue highlight and yellow text. That means the filename is doing real work, not just labelling.

You can also force a specific result for the next boot by passing arguments, and empty strings fall back to random choice. The README gives this example: python update_theme.py 'backgrounds/1.15 - [Buzzy Bees].png' 'Splashing!'.

Installing Minegrub and running the updater once

The repository offers an interactive script that handles the theme, the systemd service and the console background. The README says to run it as root and notes that it runs under sudo.

sudo ./install_theme.sh

The script also lets you pick a background instead of randomising it. If you prefer to do it by hand, the manual path starts with a clone and an optional background choice.

git clone https://github.com/Lxtharia/minegrub-theme.git
cd ./minegrub-theme
./choose_background.sh

Then copy the theme into your boot partition. The README explains the flags as recursive, update, verbose.

sudo cp -ruv ./minegrub /boot/grub/themes/

Now point GRUB at it. Open /etc/default/grub and set the theme line.

GRUB_THEME=/boot/grub/themes/minegrub/theme.txt

Regenerate the live config so the change takes effect.

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

For the dynamic parts, install fastfetch or neofetch plus Python 3 and Pillow. The README specifies sudo -H for the pip install because Pillow must be importable by root.

sudo -H pip3 install pillow

Then run the updater from anywhere. After a reboot you should see a new splash line on the logo and an updated package count.

python /boot/grub/themes/minegrub/update_theme.py

NixOS users get a flake instead. The README shows a nixosModules.default import with options under boot.loader.grub.minegrub-theme, including enable, splash, background and boot-options-count.

Where Minegrub breaks or is the wrong choice

The most concrete limitation is secure boot. The README states that secure boot prevents GRUB from loading the fonts correctly, and the only solution it offers is disabling secure boot in the BIOS. If you cannot or will not do that, expect small fonts, and there is no workaround documented.

The second failure mode is a menu that never appears. Two settings in /etc/default/grub have to be right: GRUB_TIMEOUT_STYLE=menu so the menu shows immediately, and GRUB_TERMINAL_OUTPUT="console" commented out, since that disables the graphical terminal. A distro that ships the console output line by default will show you text until you change it.

Layout is resolution-dependent. If the theme looks stretched or the buttons are the wrong size, the fix is setting GRUB_GFXMODE to a resolution your display supports. The README suggests pressing c in the real GRUB menu and running videoinfo to see what is available.

Finally, the button bar assumes four boot options. Fewer or more than that and the buttons overlap the bottom bar. The fix is editing a specific line in theme.txt, which the README links to, and the formula for other counts is in that file. If you are not comfortable editing a theme layout file, this is the wrong theme for you.

One more thing the README is silent on: rollback. There is no uninstall script documented, so reverting means undoing the GRUB_THEME line and regenerating the config yourself.

Minegrub against a conventional GRUB theme

Most GRUB themes are static asset packs. You copy a directory, set GRUB_THEME, regenerate the config, and the menu looks the same on every boot until you change the files yourself. That is the approach behind themes like HyperFluent and the various collections people share. They have no runtime component and no dependencies beyond GRUB itself.

Minegrub adds a post-boot step. That buys you changing splash text, a rotating background and a live package count, which a static theme cannot do. It also buys you dependencies: fastfetch or neofetch, Python 3, Pillow installed for root, and a scheduled job. The systemd service, the SysVinit script and the OpenRC file in the repository exist because someone has to run update_theme.py after every boot.

If you want a theme that never touches your system again after installation, a static pack is the better fit. If you want the boot menu to reflect what is on the machine, Minegrub is the version that does that.

Maintenance, licence and what updating costs you

The repository is not archived, and the last push was on 2026-09-22. Releases are spaced out: v2.0.0 in August 2023, v3.0.0 in August 2024, v3.1.0 in November 2024. Anyone adopting this should expect long gaps between tagged releases rather than a steady stream.

Upgrade cost is mostly manual. The README warns that editing theme.txt in the installed location means a later cp -r update can overwrite your changes, and suggests editing the file in the cloned repository instead so the edit survives. That is the practical difference between a one-time install and a maintainable one.

The licence is MIT. That permits use, modification and redistribution with the licence and copyright notice retained. It says nothing about the Minecraft assets or the name, and the repository does not address that question. If you plan to redistribute the theme, that is a question for your own legal advice, not something the MIT text settles.

The base theme is also translated into Spanish by a separate project, which is worth knowing if you want localised splash text or documentation.

Editorial conclusion

Adopt Minegrub if you already know your way around /etc/default/grub and want a boot menu that does something the default theme does not. Skip it on machines where secure boot cannot be turned off, on systems where GRUB_TERMINAL_OUTPUT is pinned to console by a distro default, and anywhere you cannot afford a broken boot menu. Before installing, run grub-mkconfig -V to confirm you have GRUB 2, check whether your boot directory is /boot/grub or /boot/grub2, and confirm that fastfetch or neofetch plus Pillow are installed for the root user. The theme file itself is a text file you can edit, so the boot-options-count line is the first thing to change if your menu has more or fewer than four entries.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Lxtharia/minegrub-theme on GitHub
4. README
5. Releases