btrfs-balance

Show status

$ sudo btrfs balance status path/to/filesystem

$ sudo btrfs balance start path/to/filesystem

$ sudo btrfs balance start --bg -dusage=15 path/to/filesystem

$ sudo btrfs balance start -musage=20,limit=10 path/to/filesystem

$ sudo btrfs balance start -dconvert=raid6 -mconvert=raid1c3 path/to/filesystem

$ sudo btrfs balance cancel path/to/filesystem

btrfs balance command [OPTIONS] path

btrfs balance redistributes data and metadata across devices in a btrfs filesystem. It operates on block groups (chunks), moving their contents to achieve a more even distribution or to convert between RAID profiles.
Common use cases include rebalancing after adding or removing devices, converting from one RAID level to another, and reclaiming space by consolidating partially used chunks. Filters allow targeting specific chunk types (data, metadata, system) and usage thresholds to avoid unnecessary work.

start

Start a balance operation

Show status of running or paused balance

Cancel a running balance

Pause a running balance

Resume a paused balance

Apply filters to data block groups

Apply filters to metadata block groups

Apply filters to system block groups

Run in background

Balance chunks with usage below percentage

Process at most this many chunks

Convert to specified RAID profile

Skip chunks already matching the target profile

A full balance rewrites all data and is very slow. Use filters to target only necessary chunks. Balance requires free space to relocate data. Converting RAID profiles on a busy system may take a long time.

btrfs balance is part of the btrfs-progs package for managing btrfs filesystems on Linux.

btrfs(8), btrfs-device(8), mkfs.btrfs(8)