How to Add a New Device to BTRFS File System in Linux

BTRFS – an abbreviation for the B-tree file system, is a modern Linux file system and logical volume manager optimized for fault tolerance, error detection, and repair. BTRFS uses the Copy on Write (CoW) principle and it provides features such as snapshots, RAID, and self-healing.

When you start to run out of storage space on your attached Btrfs drive, you can easily expand it by adding a new device. In this tutorial, we are going to describe how to add a new device to the existing BTRFS B-tree file system in Linux.


In order to follow along, you would require:

  • An existing btrfs file system on your Linux machine.
  • A new device to be added to Btrfs
  • A user with sudo capabilities

Add a New Device to Linux System

First of all, attach the new device to your Linux system. After that, run the command below to find out the name of the newly attached device.

$ sudo lsblk
List Block Devices
List Block Devices

In my setup, I have attached a 20GB disk drive to my Ubuntu Linux system and sdd (i.e. /dev/sdd) is the name assigned to the device as shown in the image above.

My existing btrfs drive which I am trying to expand is named /dev/sdc, which is 40GB in size and mounted on /appdata. Based on the output of the df command below, the /dev/sdc btrfs filesystem is 99% full.

$ df
Display Filesystem Disk Usage
Display Filesystem Disk Usage

Add a New Device to Existing BTRFS File System

After attaching the new device and obtaining the assigned name, the next step is to add it to the existing btrfs filesystem as follows. Replace /dev/sdd and /appdata with your own values accordingly.

$ sudo btrfs device add /dev/sdd /appdata

If no error is displayed, then the operation completed successfully.

To check the btrfs filesystem usage, run the command below. Remember to replace /appdata as appropriate.

$ sudo btrfs device usage /appdata
Show BTRFS File System Usage
Show BTRFS File System Usage

Also, run the df command again with the -h option for human-friendly output.

$ sudo df -h
Show Updated Filesystem Disk Usage
Show Updated Filesystem Disk Usage

As shown in the image above, the btrfs filesystem usage is now 66% and no longer 99%. Furthermore, the total size is now 60GB and no longer 40GB.

Balance the BTRFS File System

As a final step, it is recommended to run the command below to balance the btrfs filesystem. This would spread the data evenly across the disks. If the disk sizes are different, then the balance operation will equalize the percent utilization of the disks.

Note: The balance operation might take a while to complete depending on the amount of data involved. Therefore, it is advisable to run the command in the background by appending & if you want to continue using the terminal.

$ sudo btrfs filesystem balance /appdata &

After about 30 minutes, checking the btrfs filesystem usage information again on my Linux machine confirms that some chunks of data have been moved to the newly added device.

$ sudo btrfs device usage /appdata
Show Updated BTRFS File System Usage
Show Updated BTRFS File System Usage

Following this guide, you should now be able to add additional new devices to your btrfs filesystem. If you have any questions or you would like to share your thoughts with us regarding this article, please leave a reply below.

Got something to say? Join the discussion.