Skip to content


Btrfs is a modern filesystem for the GNU/Linux ecosystem that leverages a technique called Copy-on-Write (CoW). In essence, Copy-on-Write is a resource-management technique to implement efficiently a duplicate or copy operation on resources.

The btrfs file system is designed to meet the expanding scalability requirements of large storage subsystems. As the btrfs file system uses B-trees in its implementation, its name derives from the name of those data structures, although it is not a true acronym. A B-tree is a tree-like data structure that enables file systems and databases to efficiently access and update large blocks of data no matter how large the tree grows.

The btrfs file system provides the following important features:

  • Copy-on-write functionality allows you to create both readable and writable snapshots, and to roll back a file system to a previous state, even after you have converted it from an ext3 or ext4 file system.
  • Checksum functionality ensures data integrity.
  • Transparent compression saves disk space.
  • Transparent defragmentation improves performance.
  • Integrated logical volume management allows you to implement RAID 0, RAID 1, or RAID 10 configurations, and to dynamically add and remove storage capacity.

Basic Commands

  • mkfs.btrfs: Used to create a BTRFS filesystem
  • btrfs: Control program used to create snapshots and subvolumes and scan devices etc.

CLI Overview

mkfs.btrfs command Description
mkfs.btrfs <block device> Create a btrfs file system on a single device. For example: mkfs.btrfs /dev/sdb1
mkfs.btrfs -L <label> <block device> Create a btrfs file system on a single device with a label. For example: mkfs.btrfs -L data /dev/sdb1
mkfs.btrfs -m single <block device> Create a btrfs file system on a single device without metadata duplication. For example: mkfs.btrfs -m single /dev/sdb1
mkfs.btrfs <block device1> <block device2> Stripe the file system data and mirror the file system metadata across several devices. For example: mkfs.btrfs /dev/sde /dev/sdd
mkfs.btrfs -m raid0 <block device1> <block device2> Stripe both the file system data and metadata across several devices. For example: mkfs.btrfs -m raid0 /dev/sde /dev/sdd
mkfs.btrfs -d raid0 <block device1> <block device2> Mirror both the file system data and metadata across several devices. For example: mkfs.btrfs -d raid1 /dev/sde /dev/sdd
btrfs command Description
btrfs filesystem df <mount point> Show filesystem details of the mountpoint <mount point>.
btrfs filesystem show [<mount point>] Show filesystem usage details of the mountpoint <mount point>.
btrfs subvolume list <mount point> List btrfs subvolumes on the mountpoint <mount point>.
btrfs filesystem label <mount point> Show label of <mount point>.
btrfs filesystem label <mount point> <new label> Set a new label for <mount point>.
btrfs-scrub <path> Start a scrub on all devices of the filesystem identified by <path>.


Create a BTRFS filesystem on a single device

In the example below we create a simple btrfs filesystem on the block device /dev/sde:

mkfs.btrfs -L btrfs -m single /dev/sde

Show filesystem information

With the command btrfs filesystem usage we can list the details of all btrfs filesystems:

btrfs filesystem usage /
Label: 'Arch Linux'  uuid: 924860ba-1a5d-4a3a-b516-a793afc05105
    Total devices 1 FS bytes used 24.15GiB
    devid    1 size 66.53GiB used 31.02GiB path /dev/sda3

Label: 'btrfs_volume1'  uuid: 4cc2d30c-7ffc-4604-9c09-8fccf3e61a53
    Total devices 2 FS bytes used 263.22GiB
    devid    1 size 489.05GiB used 279.01GiB path /dev/sdb
    devid    2 size 489.05GiB used 279.01GiB path /dev/sdc

Label: 'btrfs_volume2'  uuid: 315dce55-a166-4da0-9018-96889411e785
    Total devices 2 FS bytes used 112.00KiB
    devid    1 size 978.09GiB used 2.01GiB path /dev/sdd
    devid    2 size 978.09GiB used 2.01GiB path /dev/sde

Another command to show some details of a btrfs filesystem is btrfs filesystem df:

btrfs filesystem df /
Data, single: total=29.01GiB, used=26.41GiB
System, single: total=32.00MiB, used=16.00KiB
Metadata, single: total=1.01GiB, used=369.72MiB
GlobalReserve, single: total=49.39MiB, used=0.00B

Note: The btrfs filesystem df command displays more accurate information about the space used by a btrfs file system than the df command does.

Create BTRFS subvolumes

Assumed we have a free partition /dev/sda3 for an Arch Linux root system with a btrfs root filesystem.

First, format the partition /dev/sda3 with mkfs.btrfs:

mkfs.btrfs -L "ArchLinux" /dev/sda3

Next, mount the partition:

mkdir -p /mnt/target
mount /dev/sda3 /mnt/target/

Now, we can create some subvolumes. For example, we can create a subvolume for the Arch Linux root filesystem and one subvolume for the snapshots of the Arch Linux root filesystem:

btrfs subvolume create /mnt/target/@
btrfs subvolume create /mnt/target/@snapshots

In case you want to take advantage of some compression options, you need to unmount the btrfs subvolumes and mount them again using the compress=lzo option:

umount /mnt/target

Now, we mount the subvolumes using compress=lzo and some other options:

mount -o noatime,compress=lzo,space_cache,subvol=@ /dev/sda3 /mnt/target
mkdir /mnt/target/{home,.snapshots}
mount -o noatime,compress=lzo,space_cache,subvol=@snapshots /dev/sda3 /mnt/target/.snapshots

Create a RAID1 configuration

The next example shows how we can create a btrfs RAID 1 filesystem. Here we create btrfs RAID 1 system using the drives /dev/sdd and /dev/sde, which are are both partitionless disks.

mkfs.btrfs -L btrfs_volume2 -m raid1 -d raid1 /dev/sdd /dev/sde
btrfs-progs v4.13
See for more information.

Performing full device TRIM /dev/sdd (978.09GiB) ...
Performing full device TRIM /dev/sde (978.09GiB) ...
Label:              btrfs_volume2
UUID:               315dce55-a166-4da0-9018-96889411e785
Node size:          16384
Sector size:        4096
Filesystem size:    1.91TiB
Block group profiles:
  Data:             RAID1             1.00GiB
  Metadata:         RAID1             1.00GiB
  System:           RAID1             8.00MiB
SSD detected:       yes
Incompat features:  extref, skinny-metadata
Number of devices:  2
   ID        SIZE  PATH
    1   978.09GiB  /dev/sdd
    2   978.09GiB  /dev/sde

Next, we can mount the new RAID 1 system using a mounting point. As a side note, it doesn't matter if we mount sdd or sde.

For example, create a directory /media/share/volume2 to mount /dev/sdd.

mkdir -p /media/share/volume2
mount -o compress=lzo /dev/sdd /media/shareq/volume2

Note: The lzo compression mount option is used to save disk space.

Create and delete snapshots

btrfs subvolume snapshot -r / /.snapshots/@arch-`date +%F-%R`
btrfs subvolume delete /.snapshots/@arch-XYZ

Scrub a btrfs filesystem

btrfs scrub start /data/volume1/
scrub started on /data/volume1/, fsid 4cc2d30c-7ffc-4604-9c09-8fccf3e61a53 (pid=2069)
btrfs scrub status /data/volume1
scrub status for 4cc2d30c-7ffc-4604-9c09-8fccf3e61a53
        scrub started at Sat Dec 16 08:14:51 2017 and finished after 00:04:35
        total bytes scrubbed: 133.68GiB with 0 errors