BTRFS-REPLACE(8)		     BTRFS		      BTRFS-REPLACE(8)

NAME
       btrfs-replace - replace devices managed by btrfs with other device

SYNOPSIS
       btrfs replace <subcommand> <args>

DESCRIPTION
       btrfs replace is used to replace btrfs managed devices with other
       device.

SUBCOMMAND

       cancel <mount_point>
	      Cancel a running device replace operation.

       start [options] <srcdev>|<devid> <targetdev> <path>
	      Replace device of a btrfs filesystem.

	      On a live filesystem, duplicate the data to the target device
	      which is currently stored on the source device.  If the source
	      device is not available anymore, or if the -r option is set, the
	      data is built only using the RAID redundancy mechanisms.	After
	      completion of the operation, the source device is removed from
	      the filesystem.  If the srcdev is a numerical value, it is
	      assumed to be the device id of the filesystem which is mounted
	      at path, otherwise it is the path to the source device. If the
	      source device is disconnected, from the system, you have to use
	      the devid parameter format.  The targetdev needs to be same size
	      or larger than the srcdev.

	      NOTE:
		 The filesystem has to be resized to fully take advantage of a
		 larger target device; this can be achieved with btrfs
		 filesystem resize <devid>:max /path

	      Options

	      -r     only read from srcdev if no other zero-defect mirror
		     exists.  (enable this if your drive has lots of read
		     errors, the access would be very slow)

	      -f     force using and overwriting targetdev even if it looks
		     like it contains a valid btrfs filesystem.

		     A valid filesystem is assumed if a btrfs superblock is
		     found which contains a correct checksum. Devices that are
		     currently mounted are never allowed to be used as the
		     targetdev.

	      -B     no background replace.

	      --enqueue
		     wait if there's another exclusive operation running,
		     otherwise continue

	      -K|--nodiscard
		     Do not perform whole device TRIM operation on devices
		     that are capable of that.	This does not affect
		     discard/trim operation when the filesystem is mounted.
		     Please see the mount option discard for that in btrfs(5).

       status [-1] <mount_point>
	      Print status and progress information of a running device
	      replace operation.

	      Options

	      -1     print once instead of print continuously until the
		     replace operation finishes (or is cancelled)

EXAMPLES
   Replacing an online drive with a bigger one
       Given the following filesystem mounted at /mnt/my-vault

	  Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
		  Total devices 2 FS bytes used 1TiB
		  devid	   1 size 1TiB used 500.00GiB path /dev/sda
		  devid	   2 size 1TiB used 500.00GiB path /dev/sdb

       In order to replace /dev/sda (devid 1) with a bigger drive located at
       /dev/sdc you would run the following:

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

       You can monitor progress via:

	  btrfs replace status /mnt/my-vault/

       After the replacement is complete, as per the docs at
       btrfs-filesystem(8) in order to use the entire storage space of the new
       drive you need to run:

	  btrfs filesystem resize 1:max /mnt/my-vault/

EXIT STATUS
       btrfs replace returns a zero exit status if it succeeds. Non zero is
       returned in case of failure.

AVAILABILITY
       btrfs is part of btrfs-progs.  Please refer to the documentation at
       https://btrfs.readthedocs.io.

SEE ALSO
       btrfs-device(8), btrfs-filesystem(8), mkfs.btrfs(8)

6.16.1			      September 10, 2025	      BTRFS-REPLACE(8)