Create a Btrfs Filesystem Without Guessing the Profiles

You will create a Btrfs filesystem on a deliberately chosen device or image, set its label and allocation profiles, then verify the result with blkid and Btrfs itself. This guide targets mkfs.btrfs from btrfs-progs 6.6.3, installed on the system used for these examples.

Allow 10 minutes for a new image or an already identified test device. A real disk takes longer to identify safely, but the format command itself is usually quick. You need btrfs-progs, a device or image you are certain you can erase, and a backup of anything that matters.

Checkpoint 1: identify the target

Formatting is destructive. mkfs.btrfs writes a new filesystem and can make existing data inaccessible. Do not substitute a guessed device name into the commands below. Inspect the current block-device list first:

lsblk -o NAME,PATH,SIZE,FSTYPE,LABEL,MOUNTPOINTS

For a first run, use a regular file rather than a disk. The file is a useful rehearsal because mkfs.btrfs accepts file-backed images. This example creates a 256 MiB image under /tmp. It is not a replacement for testing the kernel and storage behaviour of your intended deployment.

truncate -s 256M /tmp/btrfs-test.img

If you are formatting a real device, replace the image path with the exact path you checked. The command normally needs root when the target is a block device. A regular image in a directory you own can normally be created without elevated privileges, although later mounting may still need appropriate permissions.

Checkpoint 2: choose the profiles

Choose profiles explicitly when the layout matters. The installed version uses crc32c checksums by default. On one device, metadata defaults to dup, while data defaults to single. On multiple devices, metadata defaults to raid1 and data has defaulted to single since btrfs-progs 5.8; older releases used raid0 for multiple-device data.

For a one-device filesystem, single data and dup metadata are a clear, conventional choice:

mkfs.btrfs -L test-btrfs -d single -m dup /tmp/btrfs-test.img

On a real block device, run the same command with elevated privileges only after checking the path again:

sudo mkfs.btrfs -L DATA -d single -m dup /dev/DEVICE

Use a label shorter than 256 bytes and do not put a newline in it. The label helps later identification, but it is not a safety mechanism: a command can still format the wrong device.

dup stores two logical copies of metadata, but it is not a backup. SSD controllers can remap or deduplicate physical blocks, and any device that starts failing should be replaced. For two or more independent devices, raid1 gives two copies of data and metadata, but it still does not replace backups. Do not create RAID profiles across partitions on one physical disk and mistake them for independent fault protection.

Avoid raid5 and raid6 for production here: the local manual warns that these profiles have known problems. Mixed mode, enabled with --mixed, is intended mainly for very small filesystems. It may reduce wasted space below 1 GiB, with a softer recommendation below 5 GiB, but it can reduce performance on larger filesystems and cannot be converted later.

Checkpoint 3: read the creation report

For the test command, expect a report containing the version, label, UUID, node and sector sizes, profiles, feature lists, and device path. The exact UUID and some sizes will differ. A successful report includes lines similar to these:

btrfs-progs v6.6.3
Label:              test-btrfs
Node size:          16384
Sector size:        4096
Block group profiles:
  Data:             single
  Metadata:         DUP
Number of devices:  1

The command may perform a whole-device TRIM on a capable target. Use -K or --nodiscard to suppress that creation-time operation. This does not disable discard behaviour after the filesystem is mounted.

Checkpoint 4: verify what was written

Check the label, UUID and filesystem type without mounting the image:

blkid /tmp/btrfs-test.img

Expected output includes TYPE="btrfs", the label, a filesystem UUID and a device UUID. Confirm the filesystem layout too:

btrfs filesystem show /tmp/btrfs-test.img

It should report the label, one device, the filesystem UUID and the image path. For a real multi-device filesystem, run btrfs device scan before mounting if the kernel has not discovered all members. A udev-based system normally performs that scan automatically, but a manual scan is a useful recovery step after reloading the Btrfs kernel module.

Useful choices to leave alone

The node size defaults to 16 KiB or the system page size, whichever is larger, and cannot exceed 64 KiB. The sector size is detected from the page size. Do not force a different sector size unless you know the filesystem will be mounted by a kernel with the matching page size. An incompatible choice can leave the new filesystem unmountable.

Features are selected with -O. List what this installed program supports before enabling anything for an older kernel:

mkfs.btrfs -O list-all

In btrfs-progs 6.6.3, no-holes and free-space-tree are among the defaults shown by the creation report. A feature can make a filesystem unsuitable for an older kernel, so check the oldest kernel that must mount it rather than copying a feature list from another machine.

If the command fails or the target was wrong

Without -f, mkfs.btrfs checks for a known existing filesystem and normally refuses to overwrite it. Treat that refusal as a prompt to stop and re-check the device. The -f option is an explicit overwrite request, not a repair switch.

There is no undo command for a completed format. If the target was wrong, stop using it immediately, preserve it for recovery work, and restore the data from a verified backup. If the target was only the temporary image, discard that image after the test. For a real deployment, recreate the filesystem only after confirming that the required data is safely elsewhere.

Done means

• The device or image path was identified with lsblk and is safe to format.
• The data and metadata profiles match the intended device count and failure model.
• The creation report shows the expected label, profiles and device count.
• blkid reports TYPE="btrfs" and the expected label.
• btrfs filesystem show reports the expected UUID and members.
• Any older-kernel, RAID, TRIM or backup constraints have been recorded before mounting or putting data on the filesystem.