Linux Commands

Btrfs utility examples

Btrfs, a shortened form of B Tree File System,  is a modern CoW (copy-on-write)  filesystem whose development dates back to 2007. It was later introduced into the mainline Linux kernel in 2009 and has become a robust, secure, and reliable filesystem. It ships with advanced features with a major focus on fault tolerance, redundancy, and seamless administration.

The btrfs command manages and displays information about the Btrfs file system. The Btrfs always takes a subcommand followed by other command arguments. Without any subcommands, it prints out the usage followed by all the subcommands as shown below.

$ btrfs

Let’s go a bit deeper and explore some of the utilities that Btrfs provides to manage its filesystem.

Creating a Btrfs filesystem

We need to create a btrfs filesystem to leverage the btrfs commands and utilities from the onset. In this example, I will create a btrfs filesystem from my removable USB medium on the /dev/sdb1 filesystem, which is mounted on the /media/winnie/DATA mount point.

The lsblk command lists all the block devices on your system and is a nifty tool for listing every block device attached to your system.

$ lsblk

To start off, we will unmount the file system using the umount command.

$ sudo umount /dev/sdb1

Once unmounted, we will format the volume to the btrfs filesystem using the mkfs command as shown.

$ sudo mkfs.btrfs -f /dev/sdb1

It would be best if you got an output that is similar to the one we have below. The command prints to standard out information such as the File system Label, UUID, node size, sector size, filesystem size, among other details.

After that, we will proceed and create a new mount point in which we will mount the Btrfs device.

$ sudo mkdir -v /Reports

Then we will mount the btrfs filesystem to the mount point.

$ sudo mount /dev/sdb1 /Reports

To verify that the filesystem has been properly mounted, invoke the df command shown.

$ df -Th /Reports

Creating a subvolume

A subvolume in Btrfs filesystem is a subset of the filesystem that bears its own entirely independent directory structure. You can create multiple subvolumes in a Btrfs filesystem using the create argument.

We will create sales, marketing & IT subvolumes in the newly created /Reports btrfs filesystem.

For the sales subvolume:

$ sudo btrfs subvolume create /Reports/sales

For the marketing subvolume:

$ sudo btrfs subvolume create /Reports/marketing

For the IT subvolume:

$ sudo btrfs subvolume create /Reports/IT

Listing the  subvolumes

To list the subvolumes in the Btrfs filesystem, use the list argument as shown.

$ sudo btrfs subvolume list /Reports

This displays the subvolumes created, which are basically directories within the larger Btrfs filesystem. You can view the directory hierarchy using the good old tree command shown:

$ tree /Reports

Creating a snapshot of the subvolumes

Additionally, you can use the snapshot argument to create a read and write a snapshot of your subvolume as follows. Here, we are creating a read & write snapshot called marketing-snap of the marketing subvolume.

$ sudo btrfs subvolume snapshot /Reports/marketing /Reports/marketing-snap

Additionally, you can create a read-only snapshot using the  -r flag as shown. The marketing-rosnap is a read-only snapshot of the marketing subvolume

$ sudo btrfs subvolume snapshot -r /Reports/marketing /Reports/marketing-rosnap

Check disk space usage using the ‘df’ utility

In Btrfs filesystems, checking disk space utilization using the df command can be misleading, especially when a filesystem is mounted and files copied into it.

To attain more accurate information or output, use the df command as demonstrated.

$ sudo btrfs filesystem df /Reports

Display filesystem structure using the ‘show’ utility

The show option allows you to probe the file structure of the filesystem or subvolume.

For instance, to display the file structure of the /Reports Btrfs filesystem, run the command:

$ sudo btrfs filesystem show /Reports

To check the file structure of  the marketing subvolume, execute:

$ sudo btrfs subvolume show /Reports/marketing

Force filesystem sync using the ‘sync’ utility

To force filesystem sync, invoke the sync option as shown. Take note that the filesystem should already be mounted for the sync process to proceed successfully.

$ sudo btrfs filsystem sync  /Reports

Manage devices using the ‘device’ utility

You can add another device on the mounted filesystem as follows. Here the /dev/sdc is another removable device that we are adding on the /Reports mounted filesystem.

$ sudo btrfs device add -f /dev/sdc /Reports

After adding the device, use the balance command to balance groups of blocks or chunks in a btrfs filesystem.

To delete the device from the filesystem, use the device delete command as shown.

$ sudo btrfs device delete /dev/sdc /Reports

Scrubbing of the filesystem using the ‘scrub’ directive

Scrubbing is an exercise that attempts to repair or correct damaged blocks on the btrfs file system by verifying checksums and metadata. The scrub tool runs quietly in the background without impacting other operations.

To launch scrub on all the devices located on the file system, use the scrub start command as shown.

$ sudo btrfs scrub start /Reports

To probe the status of a scrub, use the scrub status command with the -dR option.

$ sudo btrfs scrub status -dR /Reports

This will provide a very detailed report, including the time and date of the start of the scrub, duration, and any errors encountered (if any).

To cancel scrub execution, use the scrub cancel command.

$ sudo btrfs scrub cancel /Reports

If the scrub executed successfully without any issues and exited, you will get an error indicating that the cancellation failed since the scrub operating is not running.

To resume or carry on with a previously interrupted scrub, run the scrub cancel command.

$ sudo btrfs scrub resume /Reports

Again, If the scrub command is executed successfully without interruptions, you will get the notification that there is nothing to resume.


That was a general overview of some of the btrfs commands and utilities that can be used to manage and probe the status of a btrfs filesystem. We trust you have a firm grasp on managing the btrfs filesystem using the myriad of command options and utilities it offers.

About the author

Karim Buzdar

Karim Buzdar holds a degree in telecommunication engineering and holds several sysadmin certifications. As an IT engineer and technical author, he writes for various web sites. He blogs at LinuxWays.