grub-btrfs puts your btrfs snapshots into the GRUB boot menu

The GRUB menu is generated from the snapshots that already exist

The problem grub-btrfs solves is narrow and real. On a btrfs root, snapshot tools such as Snapper, Timeshift and Yabsnap keep old copies of your system in subvolumes, and getting back to one of them normally means editing a GRUB configuration by hand or dropping to a rescue shell. This project takes a different route: it reads the snapshot subvolumes, finds the kernel, initramfs and Intel or AMD microcode inside each one, and writes a matching set of menu entries into grub.cfg.

The mechanism is a shell script that plugs into GRUB's own script convention. The file that does the work is 41_snapshots-btrfs, which the manual installation places in /etc/grub.d/. The numbering matters, because GRUB executes the scripts in that directory in order, so the snapshot entries can be inserted after the standard Linux entries are generated. The script writes its output to grub-btrfs.cfg, and then the usual grub-mkconfig run picks that file up and merges it into the final grub.cfg.

The detection is broader than a plain directory listing. The tool automatically detects whether /boot lives on a separate partition, looks inside the snapshot for the kernel, initramfs and microcode, and reads the type, tags, triggers and description comments that Snapper, Timeshift and Yabsnap attach to their snapshots so the menu entry says something meaningful rather than just listing a number.

Read-only snapshots fail when /var is not a separate subvolume

The README leads with a warning rather than a feature list, and it deserves attention. Booting read-only snapshots can be tricky. If you want to use read-only snapshots, /var/log or even /var must be on a separate subvolume. Otherwise, the advice is to make sure your snapshots are writable.

The reason is visible from the design. A read-only snapshot cannot be written to during boot, and the system needs somewhere to write. When /var is inside the same subvolume as the snapshot, the boot attempt tries to write to a filesystem that is mounted read-only, and the boot fails in a way that is hard to diagnose from the GRUB menu. The project points at an issue in its tracker for the background and, importantly, ships its own solution rather than leaving you to it.

That solution lives in the initramfs/ directory of the repository, with its own readme describing how to build and use it. In other words, grub-btrfs does not only generate menu entries, it also carries the machinery needed to make a read-only snapshot bootable, and that is the part you install separately if you want read-only snapshots.

The practical advice for most desktop systems is to keep snapshots writable, or to structure the root with a separate /var subvolume before you rely on this. The read-only path is for people who have already thought about where their logs and state files go.

One command produces the entries, then grub-mkconfig merges them in

Manual use is two steps. The first runs the script that writes grub-btrfs.cfg, and the second regenerates the GRUB configuration so the new entries appear.

sudo /etc/grub.d/41_snapshots-btrfs

That command updates grub-btrfs.cfg. After it, regenerate the GRUB configuration with the command your distribution uses. On Arch Linux or Gentoo it is grub-mkconfig, on Fedora it is grub2-mkconfig, and on Debian and Ubuntu based distributions update-grub is a script that runs grub-mkconfig for you.

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

update-grub

The first block writes the snapshot menu file, the second regenerates grub.cfg on Arch and Gentoo, and the third is the Debian and Ubuntu shortcut. On Fedora the equivalent is grub2-mkconfig -o /boot/grub2/grub.cfg, with a different output path as well as a different command name, which is exactly the kind of difference that trips people up when they copy an Arch command onto a Fedora box.

This two-step split is also why the project ships a daemon. The generation itself is cheap, but the regeneration of the full GRUB configuration is the part that takes time, and the documentation explains that the process can be automated to run whenever snapshots are created or deleted, with the mechanism depending on your init system.

GRUB_BTRFS_MKCONFIG is where distributions disagree

The configuration file at /etc/default/grub-btrfs/config is where you adapt the tool to a distribution, and the documentation is clear that the defaults assume Arch and Gentoo. The variable to check first is GRUB_BTRFS_MKCONFIG, which holds the command used to regenerate the GRUB configuration. On most systems that is grub-mkconfig, and on Fedora it is grub2-mkconfig, so the value would be set as follows.

GRUB_BTRFS_MKCONFIG=/sbin/grub2-mkconfig

The same class of problem applies to the paths. On most distributions the GRUB installation lives in /boot/grub, so the default works, and where it does not you change the setting rather than editing the script. On Fedora the GRUB directory is /boot/grub2, which is what GRUB_BTRFS_GRUB_DIRNAME is for. A third variable, GRUB_BTRFS_SCRIPT_CHECK, names the command used to check the GRUB scripts, which on Fedora is grub2-script-check.

The broader point for an adopter is that grub-btrfs is a script that shells out to distribution-specific commands, and the configuration file exists precisely because those names and paths are not standardised. The documentation says many other distributions work out of the box, but it also warns that file locations and command names differ, so the first thing to check after installation is that GRUB_BTRFS_MKCONFIG points at a command that exists on your machine.

grub-btrfsd watches the snapshot directory with inotify

The daemon, grub-btrfsd, exists so that the menu does not go stale. It watches a directory you give it, using inotify, and updates the GRUB menu when it sees a snapshot created or deleted. Using it requires inotify-tools, which the manual installation lists as a dependency needed only for the daemon.

The daemon takes the directory to watch as a command line argument, and it has a small set of options. The directory argument is normally called SNAPSHOTS_DIRS, and it takes space separated paths, so several snapshot roots can be watched at once, each inheriting the same settings such as recursion. For Snapper and Yabsnap the usual value is /.snapshots.

The Timeshift case is the fiddly one, and the options exist for a reason. Timeshift versions before 22.06 stored snapshots under /run/timeshift/backup/timeshift-btrfs, and that is what the -o flag, or --timeshift-old, selects. Newer versions, 22.06 and later, mount snapshots under /run/timeshift/$PID/backup/timeshift-btrfs, where $PID is the process ID of the running Timeshift session, and that PID changes every time Timeshift is opened. The -t flag, or --timeshift-auto, makes the daemon detect the right directory itself, and when it is set the SNAPSHOTS_DIRS argument has no effect.

The remaining options are ordinary daemon hygiene: -c or --no-color to drop colour codes from the output, -l or --log-file to choose where log messages go, -s or --syslog for syslog, -r or --recursive to watch subdirectories, -v for more verbose logging and -h for a short help message. The systemd unit grub-btrfsd.service and the OpenRC variant grub-btrfsd.initd are both in the repository, and the Makefile builds with SYSTEMD true and OPENRC false by default, so a distribution build can change those with the INITCPIO, SYSTEMD and OPENRC variables.

Packaging varies more than the configuration does

Installation goes through a package manager on the three distributions the project documents, and each path has its own wrinkle. On Arch Linux the package is in the extra repository and installs with pacman. On Kali Linux it is in the Kali repository and installs with apt, and the documentation notes that booting read-only snapshots is fully supported there when btrfs is chosen as the file system during a standard installation. On Gentoo the package lives only in the Gentoo User Repository, so the GURU has to be enabled first, and if you run systemd the USE-Flag systemd must be set or you get the OpenRC daemon instead.

pacman -S grub-btrfs

apt install grub-btrfs

The Arch command pulls the package from the extra repository, and the apt command does the same on Kali. The manual route is a make install, with make help available to show the options, and the documented dependencies are btrfs-progs, grub, bash greater than version 4, and awk, either gawk or mawk. The install target checks for root and refuses to run otherwise, printing a message telling you to run it as root, and it also installs the man page, since the documentation repeatedly points at man grub-btrfs for the full option list.

The build system also exposes variables for packagers: PREFIX defaults to /usr, the boot directories are set per distribution with BOOT_DIR_DEBIAN and BOOT_DIR_FEDORA, and GRUB_UPDATE_EXCLUDE and INSTALL_DOCS control whether the update script is installed and whether documentation is included.

GPL-3.0 licensing and a release that trails the commits

The licence is GPL-3.0. For a script that you install into /etc/grub.d/ and that reads your system's snapshot layout, the practical implication is that redistribution of modified versions carries the source and notice obligations of the licence. The repository carries a LICENSE file at its root. That is a licensing fact rather than legal advice, and for most home users installing from a distribution repository the question never arises, since the packager has already handled it.

The maintenance picture is the part to keep an eye on. The repository is not archived, the default branch is master, and the last push was on 2026-08-24, so work is still landing. The tagged releases are further back: v4.14 was published on 2025-09-17, 4.13 on 2023-06-09 and 4.12 on 2022-11-23. The gap between 4.13 and 4.14 was just over two years, so the release cadence has been uneven.

The upgrade path is straightforward for distribution users, since pacman or apt handles it, and the upgrade risk is concentrated in the two places where the script touches your system: the path of the GRUB configuration it writes, and the command it runs to regenerate it. If you have edited the GRUB_BTRFS_MKCONFIG value in /etc/default/grub-btrfs/config, that file is what a package upgrade will try to preserve, and it is worth checking it after an update rather than assuming.

Editorial conclusion

grub-btrfs fits a Linux user who relies on btrfs snapshots for recovery and wants the boot menu to expose them without hand-writing menu entries, and it ships as a package on Arch, Kali and Gentoo. It does not fit a system whose /var is not a separate subvolume and whose snapshots are read-only, because that configuration cannot boot without the extra initramfs solution described in the project documentation. Before enabling it, read the read-only warning, set GRUB_BTRFS_MKCONFIG in /etc/default/grub-btrfs/config to match your distribution, and run make help to see what the install target offers on your system.

Frequently asked questions

Official sources

1. Antynea/grub-btrfs on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases