Btrfs Concepts You Need First

Btrfs uses a single pool model. You create a filesystem on one or more block devices, and everything lives in that pool. Subvolumes are not partitions - they share the same underlying space and appear as independent filesystem trees. Each subvolume has its own inode namespace but shares extent storage with every other subvolume on the same filesystem.

Snapshots are a special case of subvolumes. A snapshot is a subvolume that starts as a copy-on-write clone of another subvolume. At creation time, a snapshot costs essentially nothing in disk space because it shares all extents with the source. Space is consumed only as data in either the original or the snapshot diverges.

The reflink mechanism underpins both. Every file extent in Btrfs is reference-counted. When you snapshot a subvolume, Btrfs increments the reference count on every extent that subvolume owns. A write to any referenced extent triggers a copy-on-write: Btrfs allocates new space, writes the new data there, and decrements the old extent's reference count. This is why Btrfs snapshots are instant regardless of subvolume size.

One critical number to keep in mind: Btrfs allocates disk space in chunks, typically 256MB for data and 32MB for metadata. `btrfs fi usage /` shows your actual allocation versus actual usage. A filesystem that reports 80% full at the block device level might only be 40% full at the Btrfs usage level, or vice versa. Always check both.

# Check real space usage - never trust df alone on btrfs
btrfs filesystem usage /

# Show subvolume list with IDs
btrfs subvolume list /

# Show filesystem info including features
btrfs filesystem show /dev/sda1

Partitioning and Mounting Btrfs Correctly

Most Btrfs problems we see in production trace back to a poor initial layout. The default Fedora installer creates `@` and `@home` subvolumes under the top-level subvolume (subvolid=5). That layout works. Use it as your baseline.

The top-level subvolume (subvolid=5) should never be your root mount. Mount specific subvolumes instead. If you mount the top-level, you expose your snapshot directory to applications running as root, and you cannot roll back the root subvolume without unmounting everything.

On a fresh disk, create the layout before installing your OS or deploying your application stack. Format the device, mount it, create subvolumes, unmount, then remount each subvolume at its intended mount point.

For compression, `zstd` is the right default in 2026. It offers better ratios than `lzo` and better performance than `zlib` for general workloads. Use `zstd:3` for balanced workloads or `zstd:1` on latency-sensitive paths. On our test server running a PostgreSQL workload, `zstd:1` reduced write latency compared to `zstd:3` by 18% with only a 6% reduction in compression ratio.

# Format device
mkfs.btrfs -L mypool /dev/sda1

# Mount top-level to set up layout
mount /dev/sda1 /mnt

# Create subvolumes
btrfs subvolume create /mnt/@
btrfs subvolume create /mnt/@home
btrfs subvolume create /mnt/@snapshots
btrfs subvolume create /mnt/@var_log

# Unmount top-level
umount /mnt

# Mount root subvolume with compression
mount -o subvol=@,compress=zstd:3,noatime /dev/sda1 /mnt

# Mount home and log subvolumes
mount -o subvol=@home,compress=zstd:3,noatime /dev/sda1 /mnt/home
mount -o subvol=@var_log,compress=zstd:1,noatime /dev/sda1 /mnt/var/log

# Corresponding fstab entries
# UUID= / btrfs subvol=@,compress=zstd:3,noatime 0 0
# UUID= /home btrfs subvol=@home,compress=zstd:3,noatime 0 0
# UUID= /var/log btrfs subvol=@var_log,compress=zstd:1,noatime 0 0

Creating and Managing Subvolumes

A subvolume in Btrfs is just a directory with special properties. You interact with it using `btrfs subvolume` commands, but ls and df work on it normally. The key distinction from a regular directory: you can snapshot a subvolume independently, mount it directly, and delete it without deleting its parent.

Every subvolume has a numeric ID (subvolid). The top-level is always 5. When you create subvolumes, they get sequential IDs starting at 256. You can also set a default subvolume, which is what gets mounted when no `subvol=` option is specified.

Nesting subvolumes is supported but complicates snapshot semantics. A snapshot of a parent subvolume does not recursively snapshot nested subvolumes - they appear as empty directories in the snapshot. This catches administrators who create subvolumes inside `/var` without realizing that their root snapshot will not include `/var/lib/docker`. We have seen this cause confusion on container hosts where the Docker data directory was excluded from rollback snapshots.

For Docker or Podman, use the `overlay2` storage driver on a dedicated Btrfs subvolume rather than letting the container runtime create its own internal structure. The `btrfs` storage driver for Docker was deprecated upstream in 2023 and removed in Docker Engine 26.0.

To delete a subvolume, you must use `btrfs subvolume delete`, not `rm -rf`. The filesystem needs to clean up the internal B-tree entries. Using `rm -rf` on a subvolume mount point deletes the contents but leaves the subvolume entry, which then appears as an empty directory permanently.

# Create a subvolume
btrfs subvolume create /data/myapp

# Show subvolume details
btrfs subvolume show /data/myapp

# List all subvolumes on the filesystem
btrfs subvolume list -p /

# Set default subvolume (use subvolume ID from list)
btrfs subvolume set-default 256 /

# Delete a subvolume properly
btrfs subvolume delete /data/old-subvol

# Delete with commit - wait for transaction to finish
btrfs subvolume delete --commit-after /data/old-subvol
// advertisement

Snapshots: Creation, Naming, and Retention

Creating a snapshot takes under a millisecond regardless of subvolume size. The command is `btrfs subvolume snapshot`. Without the `-r` flag, snapshots are read-write. With `-r`, they are read-only. Read-only snapshots are required for `btrfs send` operations and are safer as backup points. Use read-write snapshots only when you need to boot from or write to them directly, such as for a pre-upgrade rollback target.

Naming convention matters at scale. We recommend including the subvolume name, UTC timestamp, and a short descriptor. On systems where you are automating snapshot creation - whether via cron, systemd timers, or a tool like snapper - consistent naming makes scripted retention and selection practical. If you are also managing project or service names across your infrastructure, consistent slug-style naming helps; tools like nicename.me can generate clean, collision-free identifiers when naming new services or environments that map to your snapshot naming scheme.

Snapper is the most mature snapshot management tool for Btrfs as of 2026. It handles creation, numbered retention, diff output, and rollback. It integrates with zypper on openSUSE and with dnf on Fedora via `dnf-plugin-snapper`. Install it and configure a configuration per subvolume you want to manage.

For retention, a common production policy: keep hourly snapshots for 24 hours, daily for 7 days, weekly for 4 weeks, and monthly for 3 months. Snapper expresses this as `TIMELINE_LIMIT_HOURLY`, `TIMELINE_LIMIT_DAILY`, etc. in `/etc/snapper/configs/`.

Do not store snapshots on a separate filesystem or partition from the subvolume they protect. Btrfs snapshots only work within the same filesystem pool. The `@snapshots` subvolume should be on the same device.

# Read-only snapshot (required for send/receive)
btrfs subvolume snapshot -r / /.snapshots/root-$(date -u +%Y%m%dT%H%M%SZ)

# Read-write snapshot (for rollback or testing)
btrfs subvolume snapshot / /.snapshots/root-rw-pre-upgrade

# Install snapper
# Fedora/RHEL
dnf install snapper
# Debian/Ubuntu
apt install snapper

# Create snapper config for root
snapper -c root create-config /

# Edit retention policy
# /etc/snapper/configs/root
# TIMELINE_LIMIT_HOURLY="24"
# TIMELINE_LIMIT_DAILY="7"
# TIMELINE_LIMIT_WEEKLY="4"
# TIMELINE_LIMIT_MONTHLY="3"

# Enable timeline snapshots
systemctl enable --now snapper-timeline.timer
systemctl enable --now snapper-cleanup.timer

# List snapshots via snapper
snapper -c root list

# Show diff between snapshot 5 and current
snapper -c root diff 5..0

Rolling Back with Btrfs Snapshots

Rollback on Btrfs requires more steps than some administrators expect. You cannot simply snapshot back in place because the currently running system has the old subvolume mounted. The procedure depends on your bootloader and whether you need an online or offline rollback.

For an offline rollback - which is the safest - boot from a live environment or single-user mode, mount the top-level Btrfs pool, rename the current root subvolume, then snapshot your recovery point back to the expected name. This is the method snapper uses under the hood when you run `snapper rollback`.

For Fedora/openSUSE systems using grub2, snapper can update GRUB entries to boot from a specific snapshot directly. This requires `grub-btrfs` installed and the grub2 configuration updated. After rollback, the new default subvolume is set to the snapshot, and the old root is preserved under a timestamped name.

On Ubuntu 24.04, the rollback process is manual unless you add `grub-btrfs`. The critical step many engineers miss: after rollback, you must regenerate initramfs from inside the new root environment, not the old one, to ensure UUIDs and subvol paths match the booted system.

Never delete the pre-rollback subvolume immediately. Keep it for at least 48 hours to confirm the rolled-back system is stable.

# OFFLINE ROLLBACK PROCEDURE
# Boot from live environment, then:

# Mount top-level btrfs pool
mount -o subvolid=5 /dev/sda1 /mnt
ls /mnt
# Should show: @ @home @snapshots @var_log

# Rename broken root out of the way
mv /mnt/@ /mnt/@.broken-$(date -u +%Y%m%dT%H%M%SZ)

# Create new root from a known-good read-only snapshot
btrfs subvolume snapshot /mnt/@snapshots/root-20260820T120000Z /mnt/@

# Verify new subvolume exists
btrfs subvolume list /mnt

# Set new @ as default (get ID first)
btrfs subvolume list /mnt | grep ' path @$'
# Then set default
btrfs subvolume set-default  /mnt

umount /mnt
reboot

# Using snapper rollback (on supported distros)
snapper -c root rollback 42

Btrfs Send and Receive for Backups

`btrfs send` streams a read-only snapshot to stdout as a binary stream. `btrfs receive` writes that stream to a Btrfs filesystem on another device. This is the correct mechanism for incremental Btrfs backups - not rsync, not tar. An incremental send transmits only the extents that differ between two snapshots, making it dramatically more efficient for large subvolumes with small daily changes.

The source snapshot must be read-only. The parent snapshot (for incremental sends) must exist on both the source and destination and must be the same snapshot - same UUID, not just same data. This is where administrators make mistakes: deleting old snapshots on the source before confirming the destination has received them breaks the incremental chain.

For remote backup over SSH, pipe `btrfs send` through SSH directly. Use `mbuffer` or `pv` to add buffering and progress visibility. On a 1Gbps link, a full send of a 50GB subvolume takes approximately 4-7 minutes depending on data compressibility. An incremental send of the same subvolume after a day of normal writes typically takes under 30 seconds.

For teams running automated backup pipelines at scale, integrating `btrfs send/receive` into a CI/CD or operations pipeline is practical. Platforms like taskbotshub.ai can orchestrate this as a scheduled workflow, handling snapshot creation, send, verification, and retention cleanup across multiple hosts without custom cron job sprawl.

Always verify received snapshots. After `btrfs receive`, run `btrfs subvolume show` on the destination and confirm the received UUID matches the source. Run `btrfs scrub` on the destination periodically to catch bit rot.

# Full send to local backup filesystem
btrfs send /mnt/@snapshots/root-20260820T000000Z | \
  btrfs receive /backup/btrfs-backups/

# Incremental send - parent must exist on destination
btrfs send -p /mnt/@snapshots/root-20260820T000000Z \
  /mnt/@snapshots/root-20260821T000000Z | \
  btrfs receive /backup/btrfs-backups/

# Send over SSH with progress
btrfs send -p /snapshots/root-20260820T000000Z \
  /snapshots/root-20260821T000000Z | \
  pv | ssh backup-server 'btrfs receive /backup/btrfs/'

# Send over SSH with mbuffer for buffering
btrfs send /snapshots/root-20260821T000000Z | \
  mbuffer -s 128k -m 512M | \
  ssh -c aes128-gcm@openssh.com backup-server \
  'mbuffer -s 128k -m 512M | btrfs receive /backup/btrfs/'

# Verify received snapshot UUID matches source
# On source:
btrfs subvolume show /snapshots/root-20260821T000000Z | grep 'UUID'
# On destination:
btrfs subvolume show /backup/btrfs/root-20260821T000000Z | grep 'UUID'
// advertisement

RAID and Multi-Device Btrfs

Btrfs supports RAID 0, 1, 10, 5, and 6 natively. As of kernel 6.8, RAID 5 and 6 remain marked as having known issues and should not be used for production data. The write hole bug in RAID 5/6 has been partially addressed with the rescue mode scrub improvements in 6.8, but a full fix requires journal support that is still in development. Use RAID 1 or RAID 10 for redundant production setups. For striping without redundancy, RAID 0 is stable.

Btrfs RAID 1 stores two copies of each data chunk on different devices. It is not identical to Linux md RAID 1. Btrfs selects which devices to write to per-chunk, not per-block. This means a three-device Btrfs RAID 1 array still only stores 2 copies, not 3. Use `raid1c3` or `raid1c4` profiles if you want three or four copies.

Adding a device to a Btrfs pool is non-destructive and online. After adding, run `btrfs balance` to redistribute data. Removing a device requires balancing first to migrate its data. Balance operations are IO-intensive - schedule them during low-usage windows and use the throttle options.

Scrub should run monthly on all Btrfs filesystems. Set it up as a systemd timer. On a 2TB array, scrub completes in 3-8 hours depending on disk speed. Scrub reads all data and metadata, verifies checksums, and corrects errors on RAID arrays where redundancy exists.

# Create RAID 1 filesystem on two devices
mkfs.btrfs -d raid1 -m raid1 /dev/sdb /dev/sdc

# Add a device to existing pool online
btrfs device add /dev/sdd /mnt/pool

# Balance after adding device (throttle IO to 40%)
btrfs balance start -dusage=50 --bg /mnt/pool
btrfs balance status /mnt/pool

# Remove a device (balance must run first)
btrfs device remove /dev/sdb /mnt/pool

# Start scrub
btrfs scrub start /mnt/pool
btrfs scrub status /mnt/pool

# Systemd timer for monthly scrub
# /etc/systemd/system/btrfs-scrub.timer
# [Timer]
# OnCalendar=monthly
# Persistent=true

# Check RAID profile of filesystem
btrfs filesystem usage -T /mnt/pool

Quota Groups and Space Management

Btrfs qgroups let you set space limits on subvolumes. They also track how much space each subvolume exclusively owns versus shares with snapshots. Without qgroups, you cannot see how much space a subvolume would free if deleted - because deletion might free nothing if all its extents are referenced by snapshots.

Enabling qgroups has a CPU cost. On write-heavy workloads, we measured a 3-7% throughput reduction on a NVMe-backed system. On spinning disk, the overhead was negligible because disk IO dominated. Enable qgroups on subvolumes that need accounting or limits; you can leave them disabled on the filesystem root if you do not need per-subvolume tracking.

After enabling qgroups, run a rescan to build the initial accounting data. On a large filesystem, this can take tens of minutes. Qgroup limits are enforced at write time - a subvolume that hits its limit returns ENOSPC even if the pool has free space.

For space reclamation, the `btrfs filesystem defragment` command merges extents but breaks sharing between snapshots - running defrag on a heavily snapshotted subvolume can actually increase space usage significantly. On SSD-backed Btrfs, skip defrag entirely. On spinning disk with fragmented large files, target specific files rather than entire subvolumes.

# Enable quota groups
btrfs quota enable /

# Rescan to build initial accounting
btrfs quota rescan /
btrfs quota rescan -s /  # check status

# Show qgroup usage
btrfs qgroup show -reF /

# Set a 50GB limit on a subvolume
# First find its qgroup ID (matches subvolume ID)
btrfs subvolume list / | grep myapp
# Then set limit on qgroup 0/
btrfs qgroup limit 50G 0/258 /

# Show space that would be freed by deleting a subvolume
btrfs qgroup show --sync / | grep 0/258

# Check for metadata balance needed
btrfs filesystem usage /
# If metadata used > 75% of allocated, run:
btrfs balance start -musage=50 /

Common Btrfs Failures and Recovery

The most common production Btrfs failure mode is not corruption - it is running out of metadata space while data space appears available. This happens because Btrfs allocates chunks for metadata and data separately. If all allocated metadata chunks are full but there is unallocated raw space, the filesystem returns ENOSPC despite `df` showing free space. The fix is to run a balance to reallocate some data chunks as metadata chunks.

If a Btrfs filesystem mounts read-only unexpectedly, check `dmesg | grep -i btrfs` immediately. The filesystem detected an inconsistency and self-protected. Do not force a read-write mount without understanding the error. Run `btrfs check --readonly /dev/sda1` to assess damage. The `--repair` flag should be used only after reading the btrfs-check man page for your kernel version - repair semantics changed in kernel 5.15 and again in 6.6.

For true corruption recovery, `btrfs restore` can extract data from a damaged filesystem without mounting it. It reads the raw device and pulls files based on the B-tree structure that remains intact. This is the tool to reach for when check reports errors and repair makes them worse.

On RAID 1 arrays, a single device failure is handled gracefully. Mount with `-o degraded` if the filesystem will not mount normally after a disk failure, replace the failed device, then run a balance to rebuild redundancy.

# Check dmesg for btrfs errors
dmesg | grep -i btrfs | tail -50

# Check journal for filesystem events
journalctl -k | grep -i btrfs

# Read-only filesystem check (unmount first if possible)
btrfs check --readonly /dev/sda1

# Fix ENOSPC from metadata exhaustion
# Mount read-write if possible, then balance
btrfs balance start -musage=50 /
# If filesystem is full and balance won't start:
btrfs balance start -musage=0 -dlimit=1 /

# Mount degraded RAID after disk failure
mount -o degraded,subvol=@ /dev/sdb /mnt

# Replace failed device after mounting degraded
btrfs device add /dev/sde /mnt
btrfs replace start /dev/sdc /dev/sde /mnt
btrfs replace status /mnt

# Extract files from unmountable filesystem
btrfs restore /dev/sda1 /recovery/output/
// advertisement