# man > btrfs-replace(8)

[BTRFS-REPLACE(8)](https://www.chedong.com/phpMan.php/man/BTRFS-REPLACE/8/markdown)                            Btrfs Manual                            [BTRFS-REPLACE(8)](https://www.chedong.com/phpMan.php/man/BTRFS-REPLACE/8/markdown)



## 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)](https://www.chedong.com/phpMan.php/man/btrfs/5/markdown).

       **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
### Example 1. 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)](https://www.chedong.com/phpMan.php/man/btrfs-filesystem/8/markdown) 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 btrfs wiki **<http://btrfs.wiki.kernel.org>** for
       further details.

## SEE ALSO
       [**mkfs.btrfs**(8)](https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/markdown), [**btrfs-device**(8)](https://www.chedong.com/phpMan.php/man/btrfs-device/8/markdown), [**btrfs-filesystem**(8)](https://www.chedong.com/phpMan.php/man/btrfs-filesystem/8/markdown),



Btrfs v5.16.2                                02/16/2022                             [BTRFS-REPLACE(8)](https://www.chedong.com/phpMan.php/man/BTRFS-REPLACE/8/markdown)