btrfs where it fits - snapshots, subvolumes, and operations · Linux

btrfs is a modern copy-on-write filesystem with features that make it ideal for specific workloads. Choosing btrfs is a deliberate choice based on the workload and the team’s operational readiness.

When to use btrfs

Use btrfs when you need:

Snapshots for atomic rollback (after a deployment or a database migration).
Subvolumes for separate logical filesystems sharing a storage pool.
Send/receive for incremental backup or replication to another host.
Built-in compression (zstd, lzo) for space-efficient storage of compressible data.

Do not use btrfs for:

Production databases that need proven, mature storage (use ext4 or xfs).
Boot disks on legacy hardware (btrfs boot support has improved but is still tricky).
Workloads where the operations team has no btrfs experience.

Creating a btrfs filesystem

Read-only / Safemkfs.btrfs— mkfs.btrfs creates a btrfs filesystem with default settings. Modern kernels support btrfs well, but btrfs has had production issues in the past; use only for specific workloads.

$ mkfs.btrfs -L data /dev/sda1

btrfs-progs v6.6
See http://btrfs.wiki.kernel.org for more information.

Label:           data
UUID:            abc12345-...

Subvolumes

Configuration changebtrfs subvolume— Subvolumes are independent filesystems that share the underlying storage pool. Each subvolume can be snapshotted, mounted, and deleted independently. The btrfs mount option subvolid=N selects which subvolume is mounted at /.

$ btrfs subvolume create /data/projects

Create subvolume '/data/projects'

Snapshots

Configuration changebtrfs snapshot— btrfs snapshots are instant (no data is copied at creation - copy-on-write). The snapshot shares data blocks with the original until either changes. -r makes the snapshot read-only, which is mandatory for send and stops the snapshot being modified by accident.

$ btrfs subvolume snapshot -r /data/projects /data/projects-snap-2026-01-01

Create a readonly snapshot of '/data/projects' in '/data/projects-snap-2026-01-01'

Without -r the snapshot is writable, and send will refuse it

btrfs subvolume snapshot defaults to a writable snapshot. Read the output line to tell them apart: with -r btrfs prints Create a readonly snapshot of ..., without it just Create a snapshot of ....

Two consequences. A writable snapshot is not a safe backup source, because anything with the path can mutate it between creation and transfer. And btrfs send rejects it outright:

ERROR: cannot send from '/data/projects-snap': not a readonly subvolume

man 8 btrfs-send is explicit - all snapshots involved in one send must be read-only, and mounting read-only is not enough, because nothing prevents another writable mount of the same subvolume.

Always create backup snapshots with -r. Take separate writable snapshots when you want a scratch clone; do not try to serve both purposes from one.

Send/receive for backup

Configuration changebtrfs send/receive— btrfs send reads a read-only snapshot and writes a change stream. btrfs receive applies it. The snapshot must have been created with -r or send exits with 'not a readonly subvolume'. Note that a bare send is a FULL send - every block crosses the network.

$ btrfs send /data/projects-snap | btrfs receive /backup/projects

At subvol /data/projects-snap
At subvol /backup/projects

A bare btrfs send sends the whole snapshot. To send only what changed, keep the previous read-only snapshot on both sides and name it as the parent:

Configuration changebtrfs incremental send— -p names the parent snapshot. Only the delta between parent and new snapshot is sent. The parent must exist on the receiving side too, with the same UUID - which is why you delete old snapshots from both sides together, never from the source alone.

$ btrfs send -p /data/projects-snap-2026-01-01 /data/projects-snap-2026-01-02 | btrfs receive /backup/projects

At subvol /data/projects-snap-2026-01-02
At snapshot /data/projects-snap-2026-01-02

Cron will hide this failure

An incremental send chain fails closed but quietly. If the parent is missing on the receiving side, or a snapshot was taken without -r, btrfs send exits non-zero and writes to stderr - which a cron job with redirected output swallows. Weeks later there is no off-host copy.

Check the exit status, not the log text:

btrfs send -p "$PARENT" "$NEW" | btrfs receive "$DEST" || \
  { logger -p daemon.err "btrfs replication failed for $NEW"; exit 1; }

Then alert on the age of the newest snapshot on the receiving side. A backup you have not confirmed arrived is not a backup.

Scrub and balance

Configuration changebtrfs scrub— btrfs scrub reads all data and metadata blocks and verifies their checksums. This is the only way to detect silent corruption from a failing disk. Run monthly on production filesystems. Long-running but uses read-only I/O for most of its time.

$ btrfs scrub start /data

scrub: started on /data, generation 42

Configuration changebtrfs balance— btrfs balance redistributes data blocks across the devices. Use when a device in a multi-device filesystem is nearly full, or when adding a new device. Balance is online and non-disruptive but uses significant I/O.

$ btrfs balance start /data

Done, had to relocate 5 out of 12345 chunks