Introduction to btrfs-progs

The btrfs-progs package contains administration and debugging tools for the B-tree file system (btrfs).

This package is known to build and work properly using an LFS 12.0 platform.

Package Information

Btrfs-progs Dependencies




LVM2-2.03.22 (dmsetup is used in tests), reiserfsprogs-3.6.27 (for tests), and sphinx-7.1.2 (required to build documentation)

Kernel Configuration

Enable the following option in the kernel configuration and recompile the kernel:

File systems --->
  <*/M> Btrfs filesystem support                                      [BTRFS_FS]

In addition to the above and to the options required for LVM2-2.03.22 and reiserfsprogs-3.6.27, the following options must be enabled for running tests:

File systems --->
  <*/M> Reiserfs support (deprecated)                              [REISERFS_FS]
  [*]     ReiserFS extended attributes                       [REISERFS_FS_XATTR]
  [*]       ReiserFS POSIX Access Control Lists          [REISERFS_FS_POSIX_ACL]
  <*/M> Btrfs filesystem support                                      [BTRFS_FS]
  [*]     Btrfs POSIX Access Control Lists                  [BTRFS_FS_POSIX_ACL]

Installation of btrfs-progs

Install btrfs-progs by running the following commands:

./configure --prefix=/usr           \
            --disable-static        \
            --disable-documentation &&


Some tests require grep built with perl regular expressions. To obtain this, rebuild grep with the LFS Chapter 8 instructions after installing pcre2-10.42.

Before running tests, build a support program:

make fssum

To test the results, issue (as the root user):

pushd tests
   sed 's/,orphan_file//' /etc/mke2fs.conf >./custom_mke2fs.conf &&
   export MKE2FS_CONFIG=$PWD/custom_mke2fs.conf                  &&
   unset MKE2FS_CONFIG && rm custom_mke2fs.conf


If the above mentioned kernel options are not enabled, some tests fail, and prevent all the remaining tests from running because the test disk image is not cleanly unmounted.

Install the package as the root user:

make install

If you have passed --disable-documentation to configure and you need the manual pages, install them by running, as the root user:

for i in 5 8; do
   install Documentation/*.$i /usr/share/man/man$i

Command Explanations

--disable-static: This switch prevents installation of static versions of the libraries.

--disable-documentation: This switch disables rebuilding the manual pages, because it requires sphinx-7.1.2.

sed 's/,orphan_file//" ...: In this version of btrfs-progs, the btrfs-convert program produces a btrfs filesystem containing errors if converting from an ext4 filesystem created with the orphan_file feature. This command creates a custom configuration file that prevents creating a filesystem with this feature.

Using the btrfs-convert Program

This version of btrfs-progs does not convert correctly ext4 filesystems to btrfs if the ext4 orphan_file feature is turned on. If you happen to convert such a filesystem, you need to first run:

tune2fs -O ^orphan_file /dev/sdxx

where /dev/sdxx is the partition of the filesystem you want to convert.


Installed Programs: btrfs, btrfs-convert, btrfs-find-root, btrfs-image, btrfs-map-logical, btrfs-select-super, btrfsck (link to btrfs), btrfstune, fsck.btrfs, and mkfs.btrfs
Installed Libraries: and
Installed Directories: /usr/include/btrfs

Short Descriptions


is the main interface into btrfs filesystem operations


converts from an ext2/3/4 or reiserfs filesystem to btrfs (see the section called “Using the btrfs-convert Program” above)


is a filter to find btrfs root


maps btrfs logical extent to physical extent


overwrites the primary superblock with a backup copy


tunes various filesystem parameters


does nothing, but is present for consistency with fstab


creates a btrfs file system