btrfs-progs: the userspace tools that administer a copy-on-write filesystem

A copy-on-write filesystem needs a matching set of tools

Btrfs is a copy on write filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. The tools exist because that administration is not simple: a copy-on-write filesystem with snapshots, checksums and multiple device profiles has more moving parts than a flat filesystem, and the day-to-day work of managing it needs dedicated commands.

The repository hosts the following utilities and also documentation. The btrfs command is the main administration tool. mkfs.btrfs is the utility to create the filesystem. There is an all-in-one binary in the busybox style with mkfs.btrfs, btrfs-image and other tools built in, selected by the name the binary is invoked under. libbtrfsutil, under LGPL v2.1, provides C and Python 3 bindings, with a separate btrfsutil Python binding published on PyPI. The manual pages and the documentation source are published on Read the Docs.

The primary language is C, the licence is GPLv2 for the tools, and the default branch is devel with master as the release branch. The top-level tree shows the shape of the project: cmds/ for the command implementations, common/ for shared code, kernel-lib/ and kernel-shared/ for the code shared with the kernel, libbtrfs/ and libbtrfsutil/ for the two libraries, mkfs/ for filesystem creation, crypto/ and convert/ for the conversion and crypto tooling, check/ and fsck.btrfs for consistency checking, and a tests/ directory with a README describing the test suite.

The documentation is published at btrfs.rtfd.io, and the project documentation in the repository points to the INSTALL file for build instructions, tests/README.md for testing and ci/README.md for CI.

The build is a classic autotools project with a documented target set

The build is autotools based, with configure.ac, Makefile.inc.in and an autogen.sh script at the top of the tree, plus a separate Makefile.extrawarn for stricter builds.

The Makefile documents its own targets in the header comment, and reading that list is the fastest way to understand what the project expects of a build system:

# Basic build targets:
#   static      build static binaries, requires static version of the libraries
#   test        run the full testsuite
#   clean       clean built binaries (not the documentation)

The full set also includes all for the main tools and the shared library, install for binaries, shared libraries and header files to the default location of /usr/local, install-static for the static variants, clean-all which also cleans the docs and generated files, and clean-dep for the header dependency files. There is a separate group of targets for the all-in-one binary, btrfs.box and its static version btrfs.box.static, where the functionality of mkfs.btrfs, btrfs-image, btrfs-convert and btrfstune is selected by the file name the binary is invoked under.

The Makefile also documents the tuning variables. V=1 prints command lines instead of running quietly, C=1 runs a checker before compilation with sparse as the default, D=1 turns off optimizations for a debugging build, and D=dflags turns on additional debugging features such as verbose, trace, abort on the first error, all of the above, and the address, thread and undefined behaviour sanitizers, plus bcheck for extended build checks.

So the build system is unusually well documented in place, which is helpful for a project that has to be compiled on a wide range of systems, which is the next point.

Old compilers and three libcs are a deliberate constraint

The build compatibility statement is short and it is the kind of detail that decides whether a project can be built in your environment.

The build is supported on the GNU C library as the primary target, and on the musl libc and uClibc-ng. The supported compilers are gcc with a minimum version of 4.8, and clang with a minimum version of 3.4.

gcc 4.8 dates from 2013 and clang 3.4 from 2013 as well, and those floors are not accidental for a filesystem tool that gets compiled into embedded images, rescue media and initramfs environments where the system compiler is whatever the vendor shipped. Supporting uClibc-ng in particular is a statement about embedded targets rather than about servers.

Build tests are done on several distributions through a GitHub Actions workflow, so the matrix of libc and compiler combinations is exercised continuously rather than asserted.

The feature compatibility rule is separate and worth knowing: the btrfs-progs of version X.Y declare support of kernel features of the same version, and new progs on an old kernel are expected to work, limited only by features provided by the kernel. So a fresh btrfs command against an old running kernel is not a mismatch to be afraid of; the limit is what the kernel itself implements.

The release cycle follows the kernel, and the tags are signed

The release policy is stated in the project documentation and it explains a lot about how the project is managed.

The major version releases are time-based and follow the cycle of the Linux kernel releases, and the cycle usually takes two months. A minor version release may happen in the meantime if there are bug fixes or minor useful improvements queued. The recent tags match that: v7.0 on 2026-05-09, v7.1 on 2026-07-14, and v6.19.1 on 2026-03-18, all roughly two months apart.

The release tags are signed with a GPG key, and the key ID is published in the project documentation, which is the practice that lets a user verify that a tag was made by the person the project says made it. Release tarballs are hosted at kernel.org, and releases with a changelog are also published on the GitHub release page. The changelog itself lives in the CHANGES file in the tree and is mirrored on the documentation site.

The static binaries deserve a separate mention because they exist for a specific reason. For each release there are static binaries of btrfs and btrfs.box, and they can be used in rescue environments. They are built for x86_64 architecture with maximum backward compatibility, inside a GitHub Actions workflow. A machine whose root filesystem will not mount is the case this is for, and it is a case that a dynamically linked tool cannot serve.

Development follows kernel conventions, down to the subject line prefix

The development model of btrfs-progs shares a lot with the kernel model, and the project spells out what that means in practice.

One logical change per patch is the first rule, with the explanation that bugfixes, cleanups and features should not be mixed, and that this will usually be pointed out during reviews. A proper subject line is the second, prefixed with btrfs-progs: subpart, and descriptive yet not too long, with a pointer to git log --oneline for inspiration. A proper changelog is the third, and the documentation is unusually specific about what is missing from changelogs: the why of the change, how something is broken, what the user-visible effects of the bug or fix are, and how an improvement helps or what the intended usecase is.

The Signed-off-by line is not mandatory for less significant changes such as typos and documentation, but is desired, because it documents who authored the change, referencing the Developer's Certificate of Origin chapter of the kernel documentation. The documentation is also reassuring about the strictness: contributions will not be rejected just for missing it, some other way of attribution will be used such as a link to the issue or pull request, and project maintainers will add their own Signed-off-by tag regardless.

That last point is worth internalising. In a project with a single primary maintainer, the review culture tends to be the maintainer's habits, and a contributor who writes patches in kernel style will find the review path smoother.

Where to report a bug, and where not to

Bug reporting has its own documented preferences, and the list is sorted by the order of preference, which tells you what the maintainers actually read.

The GitHub issue tracker comes first. Second is the mailing list [email protected], which does not require subscribing, with the warning that the mail might get overlooked in other traffic. Third is IRC on irc.libera.chat in the #btrfs channel, described as good for discussions, for example if a bug is already known, but with the caveat that reports could miss developers' attention.

And then the explicit negative: please do not use bugzilla.kernel.org for btrfs-progs bugs. That is worth noting because the kernel bugzilla is the natural guess for anyone coming from a kernel-adjacent project, and it is the one route the documentation rules out.

Development happens on the mailing list or on GitHub through issues and pull requests, and changes should be split into logical parts where possible, with documentation either included in the same patch as the code or submitted separately.

The pull request workflow is described too. Pull requests on GitHub may be code or documentation contributions, with basic build checks enabled in the GitHub Actions CI for pull requests, and the status visible on the workflow page. Open a pull request against the devel or master branch, push an update to the same branch if needed, and close it if it turns out to be wrong, a mistake, or in need of rework. If you are sure the changes do not need CI build verification, add [skip ci] to the changelog.

Where btrfs-progs is the wrong thing to be looking at

The first limit is obvious but worth stating: this is the tooling for a filesystem you already have. If you are deciding which filesystem to deploy, reading the userspace tools is not the research to do, and nothing here will tell you whether copy-on-write with checksums and snapshots is right for your workload.

The second is the size of the project. The tree includes a per-command implementation directory, a shared common/ library, separate kernel-lib/ and kernel-shared/ directories, two libraries with their own headers under include/, a crypto/ directory, a convert/ directory, a check/ implementation with fsck.btrfs, a tune/ directory, a btrfs-completion script, and shell completion support. That is a real codebase, and a patch that goes upstream is expected to fit a review model with one primary maintainer and a documented set of conventions.

The third is the toolchain floor. gcc 4.8 and clang 3.4 are fine as minimums, but the practical constraint is the libc list. Building against musl or uClibc-ng on a modern distribution means either cross-compiling or accepting that your build environment is not the same as the one you develop in.

The fourth is what a static binary does not cover. The static x86_64 build is for rescue environments on that architecture, and there is no static build for arm64 or anything else described here. On an arm64 machine with a broken root filesystem, the artefact that would help you is not in the list of what the project publishes.

The fifth is the version coupling. The progs and the kernel features are versioned together by declaration, which makes upgrades predictable and also means that staying current means taking new tools along with new kernels, and that a distribution's packaged btrfs-progs version may be older than the kernel you are running.

Editorial conclusion

btrfs-progs is the right repository to follow for anyone administering a Btrfs filesystem, because it is the upstream source of the commands themselves rather than a wrapper, because the tools, the library and the documentation all move together, and because the release cadence is tied to the kernel so the version of the tools matches the version of the filesystem features you have. It is the wrong thing to look at if you are choosing a filesystem, since a filesystem decision is not made by reading a tool's source. Before you build it, check the three things the documentation states plainly: the compiler floor of gcc 4.8 or clang 3.4 and the libc targets of glibc, musl and uClibc-ng, because an old toolchain is a real constraint on an embedded build; that the progs version X.Y declares support for kernel features of the same version, so a new progs on an old kernel is expected to work only as far as the kernel's features allow; and that the static binaries are provided for rescue environments, built for x86_64 with maximum backward compatibility, which is the artefact to take to a machine that will not boot a normal system.

Frequently asked questions

Official sources

1. kdave/btrfs-progs on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases