Command groups

btrfs-balance – balance block groups on a btrfs filesystem

The primary purpose of the balance feature is to spread block groups across all devices so they match constraints defined by the respective profiles.

btrfs-check – check or repair a btrfs filesystem

btrfs check [options] <device>
btrfs check --progress --force /dev/sde

btrfs-device – manage devices of btrfs filesystems

  • add
  • remove
  • readyq
  • scan
  • stats
  • usage
btrfs device usage -h /mnt/storage

btrfs-filesystem – command group that primarily does work on the whole filesystems

btrfs filesystem is used to perform several whole filesystem level tasks, including all the regular filesystem operations like resizing, space stats, label setting/getting, and defragmentation.


btrfs filesystem df /mnt/backup
btrfs filesystem usage /mnt/backup



btrfs filesystem du --summarize --human-readable /mnt/storage/documents


btrfs filesystem show

btrfs-property – get/set/list properties for given filesystem object

btrfs property get
btrfs property list
btrfs property set /mnt/nvme0n1p1/wine ro false

btrfs-scrub – scrub btrfs filesystem, verify block checksums

btrfs scrub is used to scrub a btrfs filesystem, which will read all data and metadata blocks from all devices and verify checksums. Automatically repair corrupted blocks if there’s a correct copy available.

Scrub is not a filesystem checker (fsck) and does not verify nor repair structural damage in the filesystem.

btrfs scrub start /mnt/raid0/software
btrfs scrub status /mnt/raid0/software
btrfs scrub cancel /mnt/raid0/software
btrfs scrub resume /mnt/raid0/software

btrfs-subvolume – manage btrfs subvolumes

btrfs subvolume is used to create/delete/list/show btrfs subvolumes and snapshots.


btrfs subvolume list -a /


btrfs subvolume create wow
btrfs subvolume snapshot hearthstone hearthstone_test


btrfs subvolume delete hearthstone_test


btrfs subvolume snapshot -r /mnt/storage/documents /mnt/storage/documents@snap-$(date +%Y-%m-%d-%H%M)


btrfs-check – check or repair a btrfs filesystem

The filesystem checker is used to verify structural integrity of a filesystem and attempt to repair it if requested. It is recommended to unmount the filesystem prior to running the check, but it is possible to start checking a mounted filesystem.

btrfs-send – generate a stream of changes between two subvolume snapshots

btrfs send [-ve] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol> [<subvol>...]
-p <parent>send an incremental stream from parent to subvol
btrfs send /mnt/storage/documents@snap-2021-06-05-1652 | sudo btrfs receive /mnt/backup
btrfs send -p /mnt/storage/documents@snap-2021-06-05-1652 /mnt/storage/documents@snap-2021-06-05-1703 | sudo btrfs receive /mnt/backup


mkfs.btrfs – create a btrfs filesystem

-d|--data <profile>Specify the profile for the data block groups. Valid values are raid0, raid1, raid5, raid6, raid10 or single or dup (case does not matter).
-m|--metadata <profile>Specify the profile for the metadata block groups. Valid values are raid0, raid1, raid5, raid6, raid10, single or dup (case does not matter).
-s|--sectorsize <size>Specify the sectorsize, the minimum data block allocation unit.
-L|--label <string>Specify a label for the filesystem. The string should be less than 256 bytes and must not contain newline characters.
--csum <type>, --checksum <type>Specify the checksum algorithm. Default is crc32c. Valid values are crc32c, xxhash, sha256 or blake2. To mount such filesystem kernel must support the checksums as well. See CHECKSUM ALGORITHMS in btrfs(5).
mkfs.btrfs --data raid0 --metadata raid0 --label storage /dev/sde /dev/sdf
mkfs.btrfs --data single --metadata single --label test --csum sha256 /dev/sdb1


UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/mnt/storage	btrfs	defaults	0	2
UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/home/leopardb/Music		btrfs	defaults,subvol=music		0	2
UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/home/leopardb/Pictures		btrfs	defaults,subvol=pictures	0	2
UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/home/leopardb/Software		btrfs	defaults,subvol=software	0	2
UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/home/leopardb/Videos		btrfs	defaults,subvol=videos		0	2
UUID=1601da41-4271-42ad-bb04-2ea3dfdf8d43	/home/leopardb/Downloads	btrfs	defaults,subvol=downloads	0	2


Move/copy a subvolume to another filesystem

Only a readonly subvolume can be sent. Thus, we need to create a readonly snapshot first:

btrfs subvolume snapshot -r /home/leopardb/Wine /mnt/storage/wine_snap_ro

Then we send and receive the read-only snapshot

btrfs send /mnt/storage/wine_snap_ro | btrfs receive /mnt/nvme0n1p1

We do a read-write snapshot of our received readonly snapshot:

btrfs subvolume snapshot /mnt/nvme0n1p1/wine_snap_ro /mnt/nvme0n1p1/wine

And we remove the readonly snapshost:

btrfs subvolume delete /mnt/storage/wine_snap_ro
btrfs subvolume delete /mnt/storage/wine

We could also keep those snapshots if we plan on doing incremental things (other topic).

Documentation from Archwiki

Checksum algorithm

$ more /sys/fs/btrfs/a751500d-2e00-4f57-b6f3-681c2eb2e22a/checksum 
sha256 (sha256-avx2)

Advanced format disks

Inspect internals

btrfs inspect-internal dump-super -f /dev/sdb1 | grep "^sectorsize"


Problem with Btrfs: