Btrfs on Debian: What the Installer Supports and How to Set Up Subvolumes and Snapshots

When you install Debian on Btrfs, Debian Installer can use Btrfs for the root filesystem and place that filesystem in a subvolume named @rootfs. A subvolume is a separately manageable filesystem tree inside a Btrfs filesystem. The installer supports this preset root layout. It does not let you design other subvolumes, such as separate locations for /home and snapshots.

After installation, you can use the btrfs command-line tools to create subvolumes and read-only snapshots, which you can view but not change. A snapshot is a point-in-time view of one subvolume. A snapshot can help you recover files locally, but it is not a separate backup. The snapshot and its source initially share data on the same filesystem.

What Debian Installer does with Btrfs

Debian 13, “Trixie,” includes the partman-btrfs component, which adds Btrfs support to partman, Debian Installer’s partitioning tool. Since version 53, the component’s recorded behavior is to put the filesystem assigned to / in a subvolume named @rootfs. The installer can then configure the bootloader to use that subvolume when starting Debian, as described in Debian bug report #964818.

This does not let you choose a custom subvolume layout during installation. The implementation record says the installer did not hard-code additional subvolumes such as @home; a separate /home might belong on another device or filesystem. The Debian package listing confirms that the installer component is available for Trixie, while the bug record describes the root-subvolume support it added.

Debian’s Btrfs wiki says the installer does not support subvolume creation, which conflicts with the recorded @rootfs behavior. Read that statement as referring to the lack of general, user-configurable subvolume management. The practical distinction is that the installer handles a predefined root subvolume, while you create other subvolumes yourself after installation.

The available documentation does not say which multi-device Btrfs or RAID layouts the current installer supports. If you plan to install across multiple disks, verify the behavior of the specific installer image and storage arrangement rather than assuming the installer will configure the layout.

Add a separate /home subvolume after installation

A Btrfs subvolume shares the filesystem’s storage pool; it is not a fixed-size partition. You can mount it separately by naming it in the mount options. To create a subvolume beside @rootfs, mount the Btrfs filesystem’s top-level subvolume, which has ID 5. Mounting it lets you see and create subvolumes at the same level as @rootfs, rather than only files inside the root subvolume. The btrfs-subvolume manual documents subvolume creation and mounting.

First install the Btrfs tools and identify the device used for /:

sudo apt install btrfs-progs
findmnt -no SOURCE /

Use the Btrfs filesystem’s actual UUID in place of UUID=... below. Mount the top level and create @home there:

sudo mkdir -p /mnt/btrfs-top
sudo mount -o subvolid=5 UUID=... /mnt/btrfs-top
sudo btrfs subvolume create /mnt/btrfs-top/@home

If /home already contains files, do not let a new mount hide them. Log out users who are writing to /home, mount @home temporarily at another directory, and copy the existing contents into it while preserving ownership, permissions, and file metadata. Before making the new mount permanent, check that the copied files are present and intact.

Add this entry to /etc/fstab, using the same filesystem UUID:

UUID=...  /home  btrfs  defaults,subvol=@home  0  0

Test the entry with sudo mount -a and confirm that /home is mounted from @home before rebooting. Keep the top-level mount separate from /; otherwise, creating @home at the wrong location could make it a child of the root subvolume instead of a sibling.

Create and manage read-only snapshots

A Btrfs snapshot is itself a subvolume. Btrfs uses copy-on-write: the snapshot and source initially share data blocks, and later changes are stored separately. The -r option creates a read-only snapshot, which provides a stable point for recovery or transfer.

With the filesystem’s top level mounted at /mnt/btrfs-top, create a directory for snapshots and take a snapshot of the currently mounted root subvolume:

sudo mkdir -p /mnt/btrfs-top/@snapshots
sudo btrfs subvolume snapshot -r / \
  "/mnt/btrfs-top/@snapshots/root-$(date +%F)"

List the subvolumes with:

sudo btrfs subvolume list /mnt/btrfs-top

Delete a snapshot you no longer need with:

sudo btrfs subvolume delete /mnt/btrfs-top/@snapshots/root-YYYY-MM-DD

Replace the example date with the snapshot’s actual directory name. Deleting a snapshot removes it from the directory view, but Btrfs may reclaim the space it referenced later; deletion does not guarantee an immediate, matching increase in free space. The Trixie btrfs-subvolume manual documents snapshot creation, listing, and deletion.

A snapshot covers the subvolume you snapshot. If /home is a separate subvolume, a snapshot of / does not capture /home as part of the same snapshot. Creating a snapshot does not configure Debian’s bootloader to offer it as a boot choice or restore the system automatically.

Snapshots remain on the same Btrfs filesystem as their source, so damage to that filesystem or its device can affect both. For another copy, Btrfs provides send and receive to transfer read-only snapshots to a different filesystem; the Debian btrfs-send manual describes full and incremental transfers. Store that destination separately if you need protection from failure of the original device.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com