BTRFS Maintenance Guide: Do's and Don'ts

BTRFS is a modern filesystem that supports features like COW (Copy-on-Write) and instant snapshots. It is more performant and space efficient than ext4 and others. It's on par with ZFS.

There are a couple things you should do and not do after setting a btrfs filesystem.


Check filesystem usage with btdu

Btdu is a disk usage profiling tool for btrfs. As you might know, regular disk profling tools and du does not report disk space correctly with btrfs. By using btdu you can see which files and directories occupy the most space.

You can install it by grabbing the binaries from its github page.


sudo btrfs balance start -v -dusage=85 /


sudo btrfs scrub start /


Enable qgroups

It's all good until your filesystem freezes the entire kernel.

Source: Myself. I've used qgroups on two computers with timeshift snapshots enabled. They started freezing. When the freeze happens, all processes simultaneously hang. You can't even reach them by network (ssh).

Final Words

This article is a living documentation, it will be continually updated as I keep using btrfs and having problems.


For scrub and balance:


My own anectodal experience and this

Always check arch wiki