btrfs-convert rewrites an ext2, ext3, ext4 or ReiserFS filesystem into Btrfs in place, keeping the original as a recoverable subvolume. Treat this as a storage migration, not a routine filesystem command: it changes the device itself. Allow time for a full filesystem check plus the conversion, since duration depends on device size, free space and file layout and cannot be predicted from the command line.
This guide uses btrfs-convert from btrfs-progs 6.6.3. Confirm the version and the source filesystem before touching the device.
$ btrfs --version
$ sudo blkid /dev/DEVICE/dev/DEVICE for the real block device, such as /dev/sdb1. Do not guess it: check the output against the device's size and mount history. The conversion operates on the device, not on a directory or mounted path.The source filesystem must be clean. For ext2, ext3 or ext4, unmount it and run the checker described by e2fsck(8).
$ sudo umount /dev/DEVICE
$ sudo e2fsck -fvy /dev/DEVICEFor ReiserFS, use its own checker instead.
$ sudo umount /dev/DEVICE
$ sudo reiserfsck -fy /dev/DEVICERead the checker manual before accepting repairs on a production disk, and do not continue if it reports unresolved errors. Skipping this preparation can produce an incorrect target filesystem even if the conversion appears to complete.
Conversion uses free space from the original filesystem. The exact requirement cannot be calculated in advance, and the resulting Btrfs metadata can occupy several gigabytes on a filesystem of a few hundred gigabytes.
$ sudo blkid /dev/DEVICE
$ sudo dumpe2fs -h /dev/DEVICE 2>/dev/null | grep -E 'Block count|Free blocks|Block size'The second command is for ext filesystems; for ReiserFS, use the ReiserFS tools to check capacity instead. A nearly full source filesystem is a poor conversion candidate: free some space or choose a larger migration plan before proceeding.
Destructive action: this is the step that rewrites the device. Confirm it one more time, make sure it is not mounted, and keep the machine on reliable power. The command below uses the documented defaults: CRC32C data checksums, a newly generated Btrfs filesystem ID, progress output, and a 16 KiB metadata node size or the system page size when that is larger.
$ sudo btrfs-convert /dev/DEVICEThe installed 6.6.3 build reports progress by default and returns status 0 when no error occurred. A non-zero status means a problem occurred; do not assume the device is ready just because some progress was printed. Save the complete terminal output and investigate before attempting anything else.
--label NEW_LABEL sets a label; --copy-label copies the source label instead.--uuid copy copies the source UUID; --uuid new is the default.--no-xattr discards extended attributes and ACLs, so do not use it casually.--no-datasum disables data checksums and sets the NODATASUM flag.--no-inline can reduce metadata use when free space is tight, at the cost of storing small files differently.For example, a planned conversion with a label and an explicit checksum algorithm:
$ sudo btrfs-convert --label ARCHIVE --checksum crc32c /dev/DEVICEUse only checksum values this build supports: crc32c, xxhash, sha256 or blake2. The kernel must also support the selected checksum when the filesystem is mounted. List feature names before using --features.
$ btrfs-convert --features list-allAfter a successful conversion, mount the new filesystem at a temporary path and check its summary.
$ sudo mkdir -p /mnt/btrfs-check
$ sudo mount /dev/DEVICE /mnt/btrfs-check
$ sudo btrfs filesystem show /mnt/btrfs-check
$ sudo findmnt /mnt/btrfs-checkCheck that expected directories and representative files are present, and compare important file counts or checksums with your backup where practical. The original filesystem is retained in a subvolume named ext2_saved for ext2/3/4, or reiserfs_saved for ReiserFS, holding a file called image.
$ sudo btrfs subvolume list /mnt/btrfs-check
$ sudo ls -lh /mnt/btrfs-check/ext2_saved/imageCheckpoint: the saved subvolume is listed and its image file exists. Use reiserfs_saved in that last command if that is your source filesystem. Keep the saved subvolume while you test mounts, services and data, and do not run a Btrfs balance while rollback still matters: changing the extent layout can make rollback impossible.
If verification fails, unmount the converted filesystem and roll back while the saved subvolume and its original extent layout are intact.
$ sudo umount /mnt/btrfs-check
$ sudo btrfs-convert --rollback /dev/DEVICERecovery: rollback is conditional. It can fail if the conversion state has changed, the saved image is missing, or an operation such as balance has altered the layout. A failed rollback needs investigation and a backup-based recovery plan; do not repeatedly run conversion commands against an uncertain device.
If the converted filesystem is correct and rollback is no longer needed, removing the saved original metadata is irreversible.
$ sudo btrfs subvolume delete /mnt/btrfs-check/ext2_savedUse reiserfs_saved for a ReiserFS conversion. This ends the rollback path; the filesystem stays usable but may retain fragmentation inherited from the source.
Once rollback is no longer required, recursive defragmentation can make file extents more contiguous, though it can take a long time and does not guarantee a particular layout.
$ sudo btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs-checkA metadata balance is also optional and can take a lot of time; it may report a soft failure from insufficient workspace, which leaves the filesystem usable but its block-group layout unchanged.
$ sudo btrfs balance start -m /mnt/btrfs-checkWarning: never run either of these before the rollback decision is final.
ext2_saved or reiserfs_saved subvolume is either intentionally retained or intentionally deleted after verification.