Read Btrfs Space Correctly with filesystem usage

Btrfs free space is not one number, and df alone will mislead you, so learn btrfs filesystem usage before you trust a capacity report. This guide covers the difference between allocated and usable space, plus a safe boundary around resizing and defragmentation. The examples match btrfs-progs v6.6.3, installed on the system used here. Allow 15 minutes for inspection; resizing or recursive defragmentation needs planning and can take substantially longer.

• You need a shell, a mounted Btrfs filesystem and read access to its mount point.
• Privilege is usually optional. Most inspection commands are ordinary user commands; reach for sudo only when a detailed report says it needs root, or your account cannot access the mount.
• Replace the path. Swap /mnt/btrfs-data for a real Btrfs mount point; do not use a file containing a Btrfs image for the resize example.

1. Confirm the filesystem and devices

Start by asking Btrfs what it can discover. With no selector, show reports all known Btrfs filesystems, including unmounted ones.

$ btrfs filesystem show
Label: 'archive'  uuid: 11111111-2222-3333-4444-555555555555
        Total devices 1 FS bytes used 12.34GiB
        devid    1 size 100.00GiB used 20.00GiB path /dev/sdb1

The label, UUID, device ID and device path are the useful parts; exact values and formatting vary. If an unprivileged scan misses a device, retry with the documented fallback that scans device nodes.

$ sudo btrfs filesystem show --all-devices

Checkpoint: write down the mount point and the device ID before changing anything. A multi-device filesystem may have several device IDs, and the resize syntax can target one of them.

2. Read the detailed space report

Use usage for the main report. It is the preferred replacement for the older, terse df subcommand.

$ btrfs filesystem usage /mnt/btrfs-data
Overall:
    Device size:              100.00GiB
    Device allocated:          20.00GiB
    Device unallocated:        80.00GiB
    Device missing:             0.00B
    Used:                       12.34GiB
    Free (estimated):           87.66GiB
    Free (statfs, df)           87.66GiB
    Data ratio:                  1.00
    Metadata ratio:              1.00
    Multiple profiles:             no

• Device unallocated is space not yet allocated to block groups. Do not add it to Free (estimated) as if they were two separate pools.
• Free (estimated) is an estimate of space usable for data across allocated and future allocations.
• Free (statfs, df) is calculated differently and is the value applications commonly see through the filesystem statistics interface. The two free values can differ, especially with multiple profiles.

A normal-user report may warn that it cannot read detailed chunk information and that RAID5/6 numbers can be incorrect. That is a reporting limitation, not proof the filesystem is damaged. Compare again with elevated privileges if you need the per-profile breakdown.

$ sudo btrfs filesystem usage --human-readable /mnt/btrfs-data

The output may then include sections such as Data,raid1, Metadata,raid1 and Unallocated. A ratio above 1 reflects redundancy or parity, so raw device capacity is not the same as effective data capacity.

3. Use df and du for narrower questions

Use df when you need allocation totals for Data, System and Metadata, not a quick free-space summary.

$ btrfs filesystem df /mnt/btrfs-data
Data, single: total=20.00GiB, used=12.00GiB
System, single: total=32.00MiB, used=16.00KiB
Metadata, single: total=1.00GiB, used=120.00MiB
GlobalReserve, single: total=512.00MiB, used=0.00B

GlobalReserve is internal emergency metadata space, not an extra user-storage category. For file and directory accounting, use du: it reports total, exclusive and shared space, which matters for snapshots and reflinked files.

$ btrfs filesystem du --summarize /mnt/btrfs-data/projects
     Total   Exclusive   Set shared  Filename
  8.00GiB      6.00GiB      2.00GiB  /mnt/btrfs-data/projects

Shared space is not safely attributed by simply adding every file's shared value: the command calculates a set-wide shared figure to account for overlapping extents. Treat these figures as Btrfs accounting, not a replacement for checking application data and snapshot policy.

4. Change a label only when the target is certain

Reading a label is harmless.

$ btrfs filesystem label /mnt/btrfs-data
archive

Setting one changes filesystem metadata. The new label must be shorter than 256 characters and must not contain a newline.

$ sudo btrfs filesystem label /mnt/btrfs-data archive-2026

Recovery: there is no separate undo operation in this command group. Restore the old value explicitly if you recorded it.

$ sudo btrfs filesystem label /mnt/btrfs-data archive

5. Treat resize as a storage change

Resizing changes the Btrfs filesystem size, not the underlying partition. Growing is usually quick, but the partition or device must already provide the additional space. Shrinking can relocate data and may take a long time. Check the device ID with show, plan the partition operation separately, and keep a tested backup.

For a single-device filesystem where device ID 1 is confirmed, this reduces the filesystem by 1 GiB:

$ sudo btrfs filesystem resize 1:-1G /mnt/btrfs-data

Warning: this is destructive if the new boundary is wrong. Do not shrink a partition until the filesystem shrink has completed and been checked; the manual states that partition recreation must retain the original starting offset. If you only need to use all available space on device 1, the documented form is:

$ sudo btrfs filesystem resize 1:max /mnt/btrfs-data
$ sudo btrfs filesystem usage /mnt/btrfs-data

Confirm the resulting Device size before changing a partition. There is no filesystem command that restores a mistakenly chosen old size; growing later cannot recover data already lost through an unsafe shrink.

6. Defragment selectively

Defragmentation operates on files on a mounted filesystem. A directory without -r does not recursively process its files; a bounded recursive run is easier to observe.

$ sudo btrfs filesystem defrag -v -r -f /mnt/btrfs-data/projects

-r descends through files but not subvolumes, mount points or directory symlinks. -f flushes each file before moving on, which limits dirty data but can make the run slower. Expect I/O load; a target extent size such as -t 64M is advisory, not a guarantee.

Warning: do not combine defragmentation with an unexamined compression policy. The -c option enables compression while processing, and the manual warns that some older kernel ranges can break reflinks and increase space use. Snapshots and deduplicated data are the reason to stop and check before using it. If this run changes the filesystem's layout, recovery means restoring from the original data or snapshot, not reversing the command.

Done means

• Confirmed the layout. You checked the mount point, filesystem UUID, device ID and devices with filesystem show.
• Read usage correctly. You used filesystem usage for the main space decision and understood its two free-space figures.
• Used the right tool. You used df for block-group allocation and du for shared file extents.
• Changed things deliberately. Any label, resize or defragmentation change was intentional, elevated only when needed, and covered by a recovery plan.
• Verified afterwards. You checked the result after every state-changing command.