{
    "mode": "man",
    "parameter": "BTRFS-REPLACE",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/BTRFS-REPLACE/8/json",
    "generated": "2026-07-27T14:49:35Z",
    "synopsis": "btrfs replace <subcommand> <args>",
    "sections": {
        "NAME": {
            "content": "btrfs-replace - replace devices managed by btrfs with other device.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "btrfs replace <subcommand> <args>\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "btrfs replace is used to replace btrfs managed devices with other device.\n",
            "subsections": []
        },
        "SUBCOMMAND": {
            "content": "cancel <mountpoint>\nCancel a running device replace operation.\n\nstart [options] <srcdev>|<devid> <targetdev> <path>\nReplace device of a btrfs filesystem.\n\nOn a live filesystem, duplicate the data to the target device which is currently stored\non the source device. If the source device is not available anymore, or if the -r option\nis set, the data is built only using the RAID redundancy mechanisms. After completion of\nthe operation, the source device is removed from the filesystem. If the <srcdev> is a\nnumerical value, it is assumed to be the device id of the filesystem which is mounted at\n<path>, otherwise it is the path to the source device. If the source device is\ndisconnected, from the system, you have to use the devid parameter format. The\n<targetdev> needs to be same size or larger than the <srcdev>.\n\nNote\nthe filesystem has to be resized to fully take advantage of a larger target device;\nthis can be achieved with btrfs filesystem resize <devid>:max /path\nOptions\n\n-r\nonly read from <srcdev> if no other zero-defect mirror exists. (enable this if your\ndrive has lots of read errors, the access would be very slow)\n\n-f\nforce using and overwriting <targetdev> even if it looks like it contains a valid\nbtrfs filesystem.\n\nA valid filesystem is assumed if a btrfs superblock is found which contains a correct\nchecksum. Devices that are currently mounted are never allowed to be used as the\n<targetdev>.\n\n-B\nno background replace.\n\n--enqueue\nwait if there’s another exclusive operation running, otherwise continue\n\n-K|--nodiscard\nDo not perform whole device TRIM operation on devices that are capable of that. This\ndoes not affect discard/trim operation when the filesystem is mounted. Please see the\nmount option discard for that in btrfs(5).\n\nstatus [-1] <mountpoint>\nPrint status and progress information of a running device replace operation.\n\nOptions\n\n-1\nprint once instead of print continuously until the replace operation finishes (or is\ncancelled)\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "",
            "subsections": [
                {
                    "name": "Example 1. Replacing an online drive with a bigger one",
                    "content": "Given the following filesystem mounted at /mnt/my-vault\n\nLabel: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1\nTotal devices 2 FS bytes used 1TiB\ndevid    1 size 1TiB used 500.00GiB path /dev/sda\ndevid    2 size 1TiB used 500.00GiB path /dev/sdb\n\nIn order to replace /dev/sda (devid 1) with a bigger drive located at /dev/sdc you would run\nthe following:\n\nbtrfs replace start 1 /dev/sdc /mnt/my-vault/\n\nYou can monitor progress via:\n\nbtrfs replace status /mnt/my-vault/\n\nAfter the replacement is complete, as per the docs at btrfs-filesystem(8) in order to use the\nentire storage space of the new drive you need to run:\n\nbtrfs filesystem resize 1:max /mnt/my-vault/\n"
                }
            ]
        },
        "EXIT STATUS": {
            "content": "btrfs replace returns a zero exit status if it succeeds. Non zero is returned in case of\nfailure.\n",
            "subsections": []
        },
        "AVAILABILITY": {
            "content": "btrfs is part of btrfs-progs. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for\nfurther details.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "mkfs.btrfs(8), btrfs-device(8), btrfs-filesystem(8),\n\n\n\nBtrfs v5.16.2                                02/16/2022                             BTRFS-REPLACE(8)",
            "subsections": []
        }
    },
    "summary": "btrfs-replace - replace devices managed by btrfs with other device.",
    "flags": [],
    "examples": [
        "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/"
    ],
    "see_also": [
        {
            "name": "mkfs.btrfs",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/json"
        },
        {
            "name": "btrfs-device",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/btrfs-device/8/json"
        },
        {
            "name": "btrfs-filesystem",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/btrfs-filesystem/8/json"
        }
    ]
}