Btrfs Filesystem

Btrfs copy-on-write filesystem — subvolume layout, snapshot management, scrub, balance, and send/receive.

Filesystem Info

Show all Btrfs filesystems — device, size, used, path

sudo btrfs filesystem show

Detailed space usage — data/metadata/system allocation and usage

sudo btrfs filesystem usage /

df-style output with Btrfs-aware allocation info

sudo btrfs filesystem df /

Subvolumes

List all subvolumes — ID, gen, top-level, path

sudo btrfs subvolume list /

Create a subvolume — lightweight namespace for snapshots and mounts

sudo btrfs subvolume create /mnt/data/@documents

Delete a subvolume — removes it and all its data

sudo btrfs subvolume delete /mnt/data/@old_snapshots

Show subvolume details — UUID, parent UUID, creation time

sudo btrfs subvolume show /

Set default subvolume — what mounts when no subvol= option given

sudo btrfs subvolume set-default 256 /mnt/data

Snapshots

Create a read-only snapshot — basis for backup and send/receive

sudo btrfs subvolume snapshot -r / /mnt/snapshots/@root-$(date +%F)

Create a writable snapshot — for testing changes with rollback

sudo btrfs subvolume snapshot / /mnt/snapshots/@root-test

List snapshots — they are subvolumes, filter by path convention

sudo btrfs subvolume list -s /

Send and Receive

Send a read-only snapshot to another Btrfs filesystem — full backup

sudo btrfs send /mnt/snapshots/@root-2026-04-10 | sudo btrfs receive /mnt/backup/

Incremental send — only changes since parent snapshot, much faster

sudo btrfs send -p /mnt/snapshots/@root-2026-04-09 /mnt/snapshots/@root-2026-04-10 | sudo btrfs receive /mnt/backup/

Scrub and Balance

Start a scrub — verify checksums, detect and fix corruption using mirrors

sudo btrfs scrub start /

Check scrub status — errors found, bytes scrubbed, duration

sudo btrfs scrub status /

Balance data across devices — rebalance after adding/removing disks

sudo btrfs balance start /

Balance only data chunks with less than 50% usage — reclaim sparse space

sudo btrfs balance start -dusage=50 /

Check balance status — running, paused, or completed

sudo btrfs balance status /

Multi-Device

Add a device to an existing Btrfs filesystem — online expansion

sudo btrfs device add /dev/sdc /mnt/data

Remove a device — migrates data off first, then detaches

sudo btrfs device remove /dev/sdb /mnt/data

Show per-device allocation — which device holds what

sudo btrfs device usage /mnt/data

Compression

Mount with zstd compression — best ratio for general workloads

sudo mount -o compress=zstd /dev/sda2 /mnt/data

fstab entry for persistent zstd compression

UUID=<uuid> /mnt/data btrfs defaults,compress=zstd,subvol=@data 0 0

Check compression ratio on a file — compsize shows actual vs apparent

sudo compsize /path/to/directory

Install compsize on Arch: sudo pacman -S compsize

Defragment and recompress existing data with zstd

sudo btrfs filesystem defragment -r -czstd /mnt/data

Quotas

Enable quota support on a filesystem

sudo btrfs quota enable /

Show quota groups — per-subvolume space accounting

sudo btrfs qgroup show /

Set a size limit on a subvolume’s qgroup

sudo btrfs qgroup limit 10G 0/256 /

COW Control

Disable COW for a directory — for VM images, databases, large files

chattr +C /var/lib/libvirt/images/

+C only applies to newly created files in the directory. Existing files keep COW. Create the directory, set +C, then populate it.

Verify COW is disabled — look for 'C' attribute

lsattr /var/lib/libvirt/images/

Snapper Integration

List snapper configs — which subvolumes are managed

sudo snapper list-configs

Create a manual snapshot with description

sudo snapper -c root create --description "before kernel update"

List snapshots managed by snapper — number, type, date, description

sudo snapper -c root list

Show changes between two snapshots — what files changed

sudo snapper -c root status 5..6

Undo changes between two snapshots — rollback specific files

sudo snapper -c root undochange 5..6

Arch + LUKS + Btrfs Patterns

Typical Arch subvolume layout on LUKS — flat layout for boot flexibility

# After cryptsetup open and mkfs.btrfs:
sudo mount /dev/mapper/cryptroot /mnt
sudo btrfs subvolume create /mnt/@
sudo btrfs subvolume create /mnt/@home
sudo btrfs subvolume create /mnt/@log
sudo btrfs subvolume create /mnt/@cache
sudo btrfs subvolume create /mnt/@snapshots
sudo umount /mnt

Mount subvolumes with recommended options for SSD + LUKS

sudo mount -o subvol=@,compress=zstd,noatime,ssd /dev/mapper/cryptroot /mnt
sudo mount -o subvol=@home,compress=zstd,noatime,ssd /dev/mapper/cryptroot /mnt/home
sudo mount -o subvol=@log,compress=zstd,noatime,ssd /dev/mapper/cryptroot /mnt/var/log