User: Password:
Subscribe / Log in / New account

Btrfs: Getting started

Benefits for LWN subscribers

The primary benefit from subscribing to LWN is helping to keep us publishing, but, beyond that, subscribers get immediate access to all site content and access to a number of extra site features. Please sign up today!

By Jonathan Corbet
December 17, 2013
LWN's guide to Btrfs
This is the second article in a series on the Btrfs filesystem; those who have not seen the first segment may wish to take a quick look. This installment will cover the basics of finding the requisite software and getting started with a Btrfs filesystem, while leaving the advanced features for the future. Using Btrfs as a simple Unix-style filesystem is a straightforward matter once the proper tools are in place.

The Btrfs filesystem code itself has been in the mainline kernel since the 2.6.29 release in early 2009. Since then, development of the in-kernel code has mostly been done upstream, so the mainline kernel contains all of the code that is deemed ready for use. In general, users wanting to use Btrfs for real work are probably best advised to stay close to the current mainline releases. Fixes are still being made at a high rate; it is probably preferable to run the fixed code than to get a demonstration of why the fixes were necessary. One can get even newer code by pulling from the Btrfs development repository, but that may be a bit too new for anybody who is not actively developing Btrfs.

The current user-space tools, which handle the creation and management of Btrfs filesystems, can be pulled from the repository at:


Until recently, the last "release" of btrfs-progs was 0.19, made in June 2009. Toward the end of November, though, the version number was set to "v3.12", inaugurating a new era in which version numbering will be tied to kernel releases. Btrfs developer Chris Mason noted at the time that he expected to make btrfs-progs releases with approximately the same frequency as the kernel going forward. Since much of the needed work is on the user-space side, this should be a welcome development for Btrfs users.

Once again, those wanting to make serious use of Btrfs are likely to want to run something close to the current versions of the supporting user-space utilities. A lot of work (and bug fixes) is going into this code, but one needs to stay current to take advantage of that work. Some distributions follow progress in the btrfs-progs repository more closely than others; Fedora 19 already has v3.12, for example, so there is no real need for Fedora users to build their own version. Users whose distribution does not track the btrfs-progs repository so closely may want to install their own version built from the repository.

Creating and mounting Btrfs filesystems

The utility to create a Btrfs filesystem is, unsurprisingly, mkfs.btrfs; it can be invoked directly or via the mkfs program. In its simplest form, it can be run as:

    mkfs.btrfs /dev/partition-name

Where partition-name is, of course, the actual name of the partition that is to contain the filesystem.

Naturally, mkfs.btrfs has a fair number of options, though fewer than some other filesystems offer. Some of those that are relevant for basic usage include --force (necessary to convince mkfs.btrfs to overwrite an existing filesystem on the target partition), --label to set a label, and --version to just print out the version number and exit. One can also specify --mixed to cause the filesystem to mix data and metadata blocks together. Normally that will slow things down, so it is only recommended for situations where space is at an absolute premium; the man page suggests only using it for filesystems up to 1GB in size.

Btrfs filesystems are made accessible via the mount command as usual. Like most non-trivial filesystems, Btrfs has a number of specialized mount options that can be used to control its behavior. Some of these options will be discussed in later installments; a few that are of general interest include:

Enables automatic defragmentation of the filesystem in the background while it is running. Comments in the documentation suggest that this feature is still under development and may not produce optimal results for all workloads.

compress [=zlib|lzo|no]
Turn on compression of data. With an argument, it specifies which compression algorithm should be used. The compress-force option forces the use of compression even on files that do not compress well.

Turns off the copy-on-write mechanism, but only for newly created files. Turning off COW removes an important integrity mechanism and disables compression and data checksumming. In a few situations (the documentation says "large database files") there may be a significant performance improvement, but most users will probably not want to use this option.

Turns off the creation of data checksums for newly created files.

A mounted Btrfs filesystem feels mostly like any other Linux filesystem. Every now and then, some differences leak out. It can be disconcerting, for example, to delete a large file and not see an increase in the amount of available free space. Look back a minute or two later, though, and the missing space will have reappeared — assuming, of course, that said large file does not exist in any snapshots. Btrfs does a lot more work in the background than many other filesystems do.

Other Btrfs tools

The btrfs-progs repository contains a number of programs beyond mkfs.btrfs. One of the more recent additions is the btrfsck filesystem check and repair tool. The man page makes the newness of this tool clear: "Considering it is not well-tested in real-life situations yet, if you have a broken Btrfs filesystem, btrfsck may not repair but cause additional damages." So users will want to think hard before running btrfsck in the --repair mode and, probably, make use of the "restore" functionality described below.

The lack of a battle-hardened btrfsck utility remains one of the top reasons why system administrators often shy away from this filesystem. But the sad truth is that the only way to really make a truly comprehensive filesystem repair tool is to observe, over time, the ways in which a filesystem can become corrupted and come up with ways to fix those problems. So btrfsck will eventually mature into a tool that can handle a wide variety of problems, but there are no easy ways to shortcut that process.

Meanwhile, anybody working with Btrfs will eventually need to make use of another tool, called simply btrfs. This tool is the Swiss Army Knife of the Btrfs world; it can be used to perform a wide variety of actions on a Btrfs filesystem. Thus, unsurprisingly, btrfs implements a large number of commands, many of which will be examined in the later parts of this series. A few that merit mention now are:

btrfs filesystem df filesystem
Provides free space information about the given filesystem with more detail than is available from the standard df command.

btrfs filesystem show [filesystem]
Print information about one or more of the available Btrfs filesystems.

btrfs filesystem defragment [file...]
Perform online defragmentation of a Btrfs filesystem; defragmentation is limited to the given files if they are specified.

btrfs restore device
This command will try to extract the data from the given device, which, presumably, contains a filesystem with problems. By using this tool prior to attempting to repair the filesystem with btrfsck, a system administrator can maximize the chances of retrieving the data from the device even if btrfsck fails badly. See this wiki page for details on how to use this tool.

btrfs scrub filesystem
Launch a "scrub" operation on the given filesystem; scrubbing involves checking metadata and data against the checksums stored in the filesystem and correcting any errors found. Scrubbing can take some time, needless to say; it can be paused and resumed with variants of the btrfs scrub command if need be.

btrfs send subvol
btrfs receive mount
Controls the send/receive functionality, which can be used to replicate filesystems remotely or to implement incremental backup operations.

The basics described thus far are enough to get started with Btrfs, treating it as just another Unix-style filesystem, possibly with added compression and data checksumming. But it's the advanced features of the Btrfs filesystem that make it truly unique in the Linux world. One of those features — the built-in multiple-device and RAID functionality — will be the subject of the next installment in this series.

(Log in to post comments)

Btrfs: Getting started

Posted Dec 18, 2013 15:40 UTC (Wed) by brodriguesneto (subscriber, #64012) [Link]


I just installed the Fedora 20 and start a btrfs lab whith this help.

Best regards.

Btrfs: Getting started

Posted Dec 18, 2013 16:35 UTC (Wed) by Paf (subscriber, #91811) [Link]


Nothing specific to the article to say here, but I wanted to say how much I love this type of technical content. This and the detailed kernel technical articles are the sort of thing that really ease the way in to dealing with new features & new areas of the kernel.

As a budding kernel programmer, this sort of thing makes my LWN subscription worth every penny.

Btrfs: Getting started

Posted Dec 18, 2013 17:25 UTC (Wed) by SEJeff (subscriber, #51588) [Link]

To echo the previous comments... Knowing my LWN subscription helps pay Jon, Jake, etc out to the various events to cover them and write articles like this is exactly why I pay for a subscription.

Please keep up with the outstanding high quality content.

Btrfs: Getting started

Posted Dec 18, 2013 17:39 UTC (Wed) by geertj (subscriber, #4116) [Link]

I know this isn't a support forum, but I'm having stablity issues with btrfs and I'm wondering how stable it currently is for other people. I have a server that crashes about once a week with an Oops in the btrfs code. This is with the stock Fedora 20 kernel.

The link below contains the call trace, and it seems I'm not the only one having it:

Btrfs: Getting started

Posted Dec 18, 2013 18:08 UTC (Wed) by masoncl (subscriber, #47138) [Link]

Please try, we'll help ;)

Btrfs: Getting started

Posted Dec 18, 2013 18:20 UTC (Wed) by proski (subscriber, #104) [Link]

It has been fixed in
The fix is in Linux 3.13-rc3, but not in any stable kernels yet. The bug looks scary to me. I would not trust my data to the kernels that have it. Even if it's just memory (not disk) corruption and it's caught early by the debugging code.

Btrfs: Getting started

Posted Dec 23, 2013 16:10 UTC (Mon) by jafo (subscriber, #8892) [Link]

Maybe 3 or 4 years ago I put btrfs on a number of our laptops as the root file-system, and it worked quite well. The only real issue we had was the (since fixed) problem where it couldn't create new files at 80% full. In the years since, I've tried again maybe 4 or 5 times and it's always ended badly. In my, admittedly limited tests with it, it seems to have been getting less stable rather than more...

It's a very ambitious project, a new filesystem, but somehow Dillon seems to have pulled it off with HAMMER.

Btrfs: Getting started

Posted Dec 18, 2013 17:57 UTC (Wed) by idupree (guest, #71169) [Link]

I tried to find how to install Fedora (19) with btrfs compression and couldn't figure it out. I ended up installing it without compression and then adding the mount option compress=lzo to fstab and asking btrfs to compress everything, but that's terrible. Is there a good way?

Btrfs: Getting started

Posted Dec 19, 2013 8:30 UTC (Thu) by koenkooi (subscriber, #71861) [Link]

I did it in a similar way with one extra step: remount it with compress=lzo right before the package installation begins. It requires jumping to the console VT in the installer.
It sucks and I wish anaconda would support compression, but the current workaround is easy enough for me.

Btrfs: Getting started

Posted Dec 19, 2013 13:22 UTC (Thu) by airman (guest, #7341) [Link]

Thanks Jon. I really hope to see more articles of this kind in the future.

Btrfs: Getting started

Posted Dec 20, 2013 17:06 UTC (Fri) by runekock (subscriber, #50229) [Link]

I run VirtualBox on my desktop systems. What are good settings for the partition that stores my virtual disks? Should I use nodatacow? Is compression possible?

Btrfs: Getting started

Posted Dec 20, 2013 17:30 UTC (Fri) by gnacux (guest, #91402) [Link]

"Considering it is not well-tested in real-life situations yet, if you have a broken Btrfs filesystem, btrfsck may not repair but cause additional damages."

Don't they have read-only mode like e2fsck?


Posted Dec 20, 2013 18:13 UTC (Fri) by corbet (editor, #1) [Link]

You have to say --repair before it will try to change things.

Copyright © 2013, Eklektix, Inc.
This article may be redistributed under the terms of the Creative Commons CC BY-SA 4.0 license
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds