mkfs.btrfs

Create a Btrfs filesystem on an empty partition

$ sudo mkfs.btrfs [/dev/sdXY]

$ sudo mkfs.btrfs [[-m|--metadata]] single [[-d|--data]] single [/dev/sdX]

$ sudo mkfs.btrfs [[-m|--metadata]] raid1 [[-d|--data]] raid1 [/dev/sdX /dev/sdY /dev/sdZ ...]

$ sudo mkfs.btrfs [[-L|--label]] "[label]" [/dev/sdX /dev/sdY ...]

$ sudo mkfs.btrfs [[-f|--force]] [/dev/sdX]

mkfs.btrfs [options] <device> [<device>...]

-L, --label <LABEL>
    Set the filesystem label. This label can be used to identify and mount the filesystem.

-U, --uuid <UUID>
    Specify the Universally Unique Identifier (UUID) for the filesystem. If not specified, a random UUID will be generated.

-d, --data <profile>
    Specify the profile for data allocation. Common profiles include single, DUP, RAID0, RAID1, RAID10, RAID5, and RAID6. Default is single for a single device.

-m, --metadata <profile>
    Specify the profile for metadata allocation. Common profiles are single, DUP, RAID0, RAID1, RAID10, RAID5, and RAID6. Default is DUP for a single device for robustness.

-O, --features <feature_list>
    Enable specific filesystem features during creation. Features are comma-separated (e.g., -O mixed-bg). Use list-all to see available features.

-s, --sectorsize <SIZE>
    Specify the sector size (physical block size) of the device, typically 4k or 512b. Defaults to the page size of the system or 4k for optimal performance.

-n, --nodesize <SIZE>
    Specify the B-tree node size, which impacts how data and metadata are stored. Defaults to 16KB for most use cases.

-f, --force
    Force the creation of the filesystem, even if the device already contains a recognized filesystem or partition table. Use with caution.

-q, --quiet
    Suppress most of the output messages during filesystem creation.

-V, --version
    Print the mkfs.btrfs version and exit.

The mkfs.btrfs command is used to format a block device or multiple devices into a Btrfs filesystem. It initializes the necessary metadata structures, including the root tree, extent tree, and checksum tree, enabling Btrfs's advanced features. These features include copy-on-write (CoW), snapshots, subvolumes, checksumming for data and metadata integrity, and built-in RAID capabilities. When executed, mkfs.btrfs will overwrite all existing data on the specified device(s), so caution is advised. It automatically sets up default profiles for data and metadata (e.g., single for data, DUP for metadata on a single device) but allows explicit configuration of redundancy levels. This utility is a fundamental part of managing Btrfs, a modern, feature-rich filesystem for Linux.

Using mkfs.btrfs will irrevocably erase all data on the target device(s). Always double-check the specified device name. While mkfs.btrfs can create multi-device filesystems with RAID profiles, managing existing RAID arrays (e.g., adding/removing devices) is handled by the btrfs device subcommand, not mkfs.btrfs. The Btrfs kernel module must be loaded to mount and utilize the created filesystem.

For a single device, mkfs.btrfs defaults to a single profile for data and a DUP profile for metadata. The DUP metadata profile on a single device provides an extra layer of protection against metadata corruption by storing two copies of all metadata blocks.

Btrfs inherently uses checksums for both data and metadata. This feature is enabled by default with mkfs.btrfs and ensures data integrity by detecting silent data corruption. If corruption is detected, Btrfs can often recover data from a redundant copy if available (e.g., with DUP or RAID profiles).

Upon creation, mkfs.btrfs establishes an initial top-level subvolume, typically with ID 5. This serves as the default mount point and can be used to create additional subvolumes and snapshots, which are core features of Btrfs's flexible storage management.

Btrfs development began at Oracle in 2007, aiming to create a next-generation filesystem for Linux, focusing on scalability, data integrity, and advanced features. The initial version of Btrfs was merged into the Linux kernel mainline in 2.6.29 (2009). mkfs.btrfs, along with other user-space utilities, is part of the btrfs-progs package, which has continuously evolved with the kernel module to provide robust filesystem management. It gained significant adoption and is considered stable for many production environments, though active development continues to refine features and performance.

btrfs(8), mount(8), fsck.btrfs(8), btrfs-progs(8)