Replace a Btrfs Device Without Losing Track of the Operation

You will replace one device in a mounted Btrfs filesystem, watch the copy, and make a larger replacement device usable after it finishes. The examples use btrfs-progs 6.6.3, installed here as btrfs. Allow 15 to 30 minutes for the commands and verification, then longer for the data transfer itself.

This is an administrative operation that changes storage and can disrupt access if you choose the wrong device. You need root access, a mounted Btrfs filesystem with a healthy replacement target, and a current backup. Keep the source and target device names visible while working. The target must be at least as large as the source.

1. Confirm the installed command and filesystem

These checks are read-only. The version identifies the local command whose behaviour this guide describes:

$ btrfs --version
btrfs-progs v6.6.3
$ command -v btrfs
/usr/bin/btrfs
$ sudo btrfs filesystem show /mnt/my-vault/

Replace /mnt/my-vault/ with the actual mount point. Record the filesystem's device IDs and paths from the final command. In the examples below, device ID 1 is /dev/sda and the new disk is /dev/sdc. Do not infer those names from the example on your own machine.

2. Check for an existing replace operation

Only one replacement should be driving the workflow. Ask for a one-time status report:

$ sudo btrfs replace status -1 /mnt/my-vault/

The output is host-specific. A running operation reports progress; a filesystem with no active replacement reports that no replace is running. The -1 option prevents status from polling continuously. Without it, status continues until the operation finishes or is cancelled.

If another exclusive Btrfs operation is in progress, you can add --enqueue to start so the request waits instead of continuing immediately. That does not make an unsafe device choice safe, and it does not remove the need to monitor the operation.

3. Start the replacement

The normal form is btrfs replace start SOURCE TARGET MOUNT_POINT. Use the source device ID when the source disk is disconnected or when you want an unambiguous filesystem reference:

$ sudo btrfs replace start 1 /dev/sdc /mnt/my-vault/

On a live filesystem, Btrfs copies the data associated with the source device to the target, then removes the source from the filesystem when the replacement completes. A source path such as /dev/sda is also accepted while that device is available. A numeric source is treated as a device ID for the filesystem mounted at the path.

The default may run in the background, so a prompt returning does not mean that the replacement is complete. The target is overwritten by the operation. Never add -f casually: it forces use of a target that appears to contain a valid Btrfs filesystem. A mounted target is not allowed even with that option.

$ sudo btrfs replace status -1 /mnt/my-vault/

Use the source ID shown by your own btrfs filesystem show output, not the literal 1 unless it really is the source ID.

4. Monitor until Btrfs reports completion

For a live progress view, omit -1:

$ sudo btrfs replace status /mnt/my-vault/

Progress, transferred bytes and the final result depend on filesystem size, load and device health, so do not script against a particular line of output. A zero exit status from a command means that command succeeded; use the status report to establish that the replacement itself has finished.

Do not remove the old disk, reboot for convenience or reuse the target while the operation is active. If the source disk is developing read errors, the -r option tells Btrfs to read from it only when no other zero-defect mirror exists. It can help a degraded array, but reads may be very slow and the result still depends on available RAID redundancy:

$ sudo btrfs replace start -r 1 /dev/sdc /mnt/my-vault/

Choose -r before starting. It is not a repair for missing redundancy or a substitute for a backup.

5. Cancel only when you have a recovery decision

Cancellation is a state-changing action. It may leave the replacement unfinished, so first capture status and decide whether you are fixing a mistaken target, responding to a failing disk, or accepting a maintenance window:

$ sudo btrfs replace status -1 /mnt/my-vault/
$ sudo btrfs replace cancel /mnt/my-vault/
$ sudo btrfs replace status -1 /mnt/my-vault/

If the cancel command fails, keep the filesystem mounted as it is and save the exact error. Do not retry with -f or disconnect a disk to force progress. Check the filesystem state and the original device mapping before choosing a new operation. There is no general undo command that reconstructs an overwritten target.

6. Expand the filesystem when the new device is larger

Replacing a smaller disk with a larger one does not automatically make all of the extra capacity available to the filesystem. After status confirms completion, inspect the device IDs again and resize the replacement device to its maximum:

$ sudo btrfs filesystem show /mnt/my-vault/
$ sudo btrfs filesystem resize 1:max /mnt/my-vault/
$ sudo btrfs filesystem usage /mnt/my-vault/

Use the replacement device's actual ID in place of 1. The resize command changes filesystem allocation metadata, so keep the backup and maintenance window in place until it succeeds. If the replacement was the same size, there may be no additional capacity to expose.

Common traps

• A path such as /dev/sda can change across boots. Prefer the device ID for a disconnected source and verify the mount point.
• -f concerns a target that looks like a valid Btrfs filesystem; it is not a generic confirmation prompt.
• status without -1 keeps polling. Use -1 in scripts and checkpoints.
• -K or --nodiscard skips the whole-device TRIM during replacement on devices that support it. It does not disable discard behaviour for a mounted filesystem.
• -B requests a foreground replacement. It changes how the command waits, not what source or target it selects.