Run a Targeted Btrfs Balance Safely

A bare btrfs balance can churn an entire filesystem for hours, so learn the filters before you run one. This guide covers checking usage first, starting a narrow balance, watching or cancelling it, and treating profile conversion as its own decision. The examples use btrfs-progs v6.6.3, the version installed on this machine. Allow 10 to 30 minutes for a small filtered run; a busy or large filesystem takes much longer.

• You need a mounted Btrfs filesystem and a root shell, or enough privilege for filesystem operations on your system.
• Replace the path. Swap /mnt/data below for your real mount point, not one copied from a different host.
• Mind the privilege split. Start, pause, cancel, resume and convert change filesystem state and normally need elevated privileges. The inspection commands are read-only but may show less detail to an unprivileged user.

1. Confirm the mount and the installed syntax

Do not start with a bare balance. With no filters, Btrfs can relocate data and metadata across the whole filesystem, burning time, CPU and IO. Check the mount first, then confirm the command version and help text.

$ findmnt -t btrfs /mnt/data
$ btrfs --version
btrfs-progs v6.6.3
$ btrfs balance start --help

The target must be a mounted Btrfs filesystem, not a block device and not an arbitrary directory. If findmnt prints nothing, stop and correct the mount point rather than guessing.

2. Check usage before moving anything

Look at logical allocation before choosing a threshold. Neither command below starts a balance.

# btrfs filesystem df /mnt/data
# btrfs filesystem show /mnt/data

• filesystem df reports allocated and used space by chunk type and profile.
• The usage filter selects block groups whose usage is at most the percentage supplied. A small value such as 10 or 20 targets sparsely used chunks and limits the first run: it does not mean that exact percentage of all files will move.
• Workspace matters. A balance normally creates a new block group before removing the old one, so compare each device's size and used values in btrfs filesystem show. That gap is the rough workspace available. A filesystem with apparently free space can still fail with ENOSPC if it lacks suitable unallocated block-group space.

3. Compact sparsely used data chunks

Start with a data-only filter. It must be attached directly to -d, with no space.

# btrfs balance start -dusage=10 /mnt/data
Done, had to relocate 2 out of 97 chunks

The counts vary by filesystem, so treat that line as the shape of success, not a promise. The command runs in the foreground. It may free block-group space for reuse, but it does not defragment files, recompress extents or change file offsets. Check the result rather than assuming a clean exit freed a specific amount.

# btrfs filesystem df /mnt/data
# btrfs balance status /mnt/data

• Raise the threshold in a separate run once the first pass finishes, for example -dusage=30 or -dusage=50. Higher thresholds move more data.
• Watch for diminishing returns. Above roughly half-used chunks, a run may mostly relocate data without shrinking the total allocation, so stop when the result no longer justifies the IO.
• Tight on workspace? The documented special case scans unused data block groups and does not need the normal balance workspace.

# btrfs balance start -dusage=0 /mnt/data

4. Watch, pause and recover a running balance

A foreground balance is cancellable from another terminal.

# btrfs balance status -v /mnt/data

• Pause keeps the run's progress and filters on the filesystem, then check with btrfs balance status.
• Resume continues a paused run, or one whose state survived an interruption, once the filesystem is mounted normally.
• Cancel abandons the remaining work. It waits for the current block group to finish first.

# btrfs balance pause /mnt/data
# btrfs balance status /mnt/data

# btrfs balance resume /mnt/data

# btrfs balance cancel /mnt/data

An interruption is safe for on-disk consistency, and a stored balance can resume after a mount. Do not use the skip_balance mount option if you intend to resume stored work. The pause, cancel and resume commands return status 2 when no balance is running, which differs from a general command failure.

5. Treat profile conversion as a separate decision

A balance can also convert block-group profiles, and conversion changes redundancy, so it deserves its own capacity and recovery plan. A multi-device filesystem could select data chunks for conversion to RAID1 with:

# btrfs balance start -dconvert=raid1,soft /mnt/data

soft leaves chunks already on the target profile alone, which is useful when an earlier conversion stopped part-way through. This example does not establish that RAID1 suits your devices or workload. Check profiles with btrfs filesystem df, confirm device count and workspace, and make sure your backup and restore path works before changing redundancy.

6. Diagnose ENOSPC without making it worse

If the command reports no space left, resist repeating it with a broader threshold straight away.

• Inspect allocation again and look for completely unused chunks first.
• Run the zero-usage filter for the block-group type you understand, -dusage=0 or the matching metadata filter. A successful empty-chunk cleanup can create enough workspace for a later targeted run.
• Schedule big runs off-peak. Balance is IO-intensive and competes with services using the filesystem; monitor the host and pause or cancel if latency becomes unacceptable.
• Keep real backups. Balance changes physical locations but preserves extent sharing and logical file layout. It is not a substitute for recovery copies, and a profile conversion is not a backup.