Getting started

From btrfs Wiki
Revision as of 15:49, 21 October 2021 by Ckujau (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This guide will help you in setting up the btrfs filesystem and using it in your Linux system.


Before you start

btrfs is a fast-moving target. There are typically a great many bug fixes and enhancements between one kernel release and the next. Therefore:

If you have btrfs filesystems, use a Linux distribution which supports btrfs or run the latest kernel.

Some distributions keep backports of recent kernels to earlier releases and it's a good idea to use them if you want to use btrfs.

If you are running a kernel two or more versions behind the latest one available from, the first thing you will be asked to when you report a problem is to upgrade to the latest kernel.

Having the latest user-space tools are also useful, as they contain additional features and tools which may be of use in debugging or recovering your filesystem if something goes wrong.

The status of btrfs was experimental for a long time, but the the core functionality is considered good enough for daily use. There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.

You should keep and test backups of your data, and be prepared to use them.

Distro support

Many distros already enable Btrfs support in their kernels and have packages for the Btrfs userspace utilities, therefore we recommend to use them. Refer to your distro for more documentation about the specifics, like package names or versions available. This wiki is focused on upstream community and for general information.

Enterprise distributions

Since February 2012, entrerprise distrubutions which support btrfs (including commercial support) are:

SUSE Enterprise Linux

With SLES11 SP2 comes support of btrfs, read more in the release notes section.

Unbreakable Enterprise Kernel Release 2 for Oracle Linux

Available for both Oracle Linux 5 and 6, also available to Oracle Linux Customers from the Oracle Unbreakable Linux Network.

Community distributions

Reporting problems

If you have a problem with btrfs, you should report it to either the Btrfs mailing list or to the IRC channel.

Creating a filesystem

Creating a filesystem of at least 1GiB is recommended.

Note: Be aware that for that size, it will report full when reaching about 75%.

btrfs as root fileystem

If you use a distro which supports btrfs, it's very likely that you decided to use btrfs as the root filesystem created during installation process. In that case, there procedure differs on each distribution and it's the best to follow their guides and rely on their installers.

As a general information, the recommended partition layout for an installation for a desktop workstation or a laptop with one drive is:

Partition Filesystem Start End Partition type
/dev/sda1 (bootloader) 0 4MiB BIOS boot partition
/dev/sda2 Btrfs/FAT32* 4MiB 1GiB EFI system partition
/dev/sda3 Swap 1GiB 4GiB Swap partition
/dev/sda4 Btrfs 4GiB 100% Linux filesystem
1) Note that if you use EFI you need a FAT32 formatted EFI System Partition.
2) If you have a very old GRUB, then it may not support Btrfs for /boot (/dev/sda2). In that case use Ext4

Creating new filesystems

If you want to create a new btrfs filesystem, you can use the mkfs.btrfs tool.

btrfs filesystems can be created on:

  • partitions (example: /dev/sdb1)
  • raw disks, without partitioning (example: /dev/sdb)

Below we refer to both of them as devices.

On single device

To create a btrfs filesystem on a single device, use the following command:

mkfs.btrfs -L mylabel /dev/disk

For example, on a partition:

mkfs.btrfs -L mylabel /dev/sdb1

Or on the full raw disk:

mkfs.btrfs -L mylabel /dev/sdb

Multiple devices

btrfs allows to create RAID consisting of multiple partitions or disks. See Using Btrfs with Multiple Devices for details and instructions.

btrfs (command)

btrfs is the control program for managing btrfs filesystems. It's most commonly used for operations like creating snapshots, creating subvolumes and scanning devices.


  • Scanning devices:
    • Scan all devices looking for btrfs filesystems, or scan just one partition
btrfs device scan
btrfs device scan /dev/sda
  • Snapshots and subvolumes
    • mount -t btrfs /dev/sda2 /mnt/btrfs
btrfs subvolume create /mnt/btrfs/new_subvol
btrfs subvolume snapshot /mnt/btrfs /mnt/btrfs/snapshot_of_root

Now it is possible to mount the subvolumes

mount -t btrfs -o subvol=new_subvol /dev/sda2 /mnt/new_subvol
mount -t btrfs -o subvol=snapshot_of_root /dev/sda2 /mnt/snap

Other tools

btrfs-debug-tree /dev/sda2 >& big_output_file
  • If a problem occures you can create an image of the fs with btrfs-image and send it to the devs. (All data will be zeroed, but metadata and the like is preserved.)
btrfs-image -c 9 /dev/sda2 /tmp/btrfs_dump.z

Further reading

Personal tools