Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Discover and administer Btrfs on Linux

By updated

Improve this page

The Btrfs file system (B-tree File System) ships with more and more modern Linux systems. It stands out through its advanced features: instant snapshots, transparent compression and native management of multiple volumes in RAID. Designed for dynamic environments, Btrfs presents itself as a modern alternative to ext4, with much greater flexibility, at the cost of more demanding administration.

In this guide, you will learn to create, mount and administer a Btrfs file system, making the most of its specific tools and tuning capabilities. If you have not read the guide to choosing a Linux file system yet, start there to grasp the basics (blocks, journaling, extents).

What you will learn

  • Create a Btrfs file system on one or several disks
  • Mount volumes and subvolumes, temporarily then via /etc/fstab
  • Choose the right mount options: compression, SSD, security
  • Take snapshots and export them with btrfs send and btrfs receive
  • Monitor integrity with scrub and react to corruption
  • Apply good practices: subvolumes, quotas, nodatacow

What is Btrfs?

The Btrfs file system (B-tree File System) was born at Oracle in 2007 with a clear goal: offer a modern, reliable system suited to large volumes. It has been in the Linux kernel since 2009 and several distributions have adopted it: openSUSE uses it by default for the root (with automatic snapshots), Fedora Workstation has made it its default file system since version 33. Unlike ext4, Btrfs is not the evolution of an existing system, but a complete redesign built for administrators' current needs.

A Copy-on-Write system

The heart of Btrfs is the Copy-on-Write (CoW) mechanism: instead of modifying blocks in place, it writes new blocks at each change, then updates the metadata. This guarantees better data integrity on a sudden power loss, allows near-instant snapshots and makes advanced features such as deduplication possible.

This principle has a performance cost for some workloads that keep rewriting the same files (databases, virtual machine images), but it allows operations ext4 cannot do without third-party tools.

Notable features

Here is what sets Btrfs apart from classic file systems. Each of these features is built into the system itself: no need to stack LVM, mdadm or third-party tools to benefit from them.

  • Native RAID: Btrfs handles RAID 0, 1 and 10 profiles without LVM or mdadm (RAID 5/6 profiles exist but remain discouraged, see below).
  • Transparent compression (zlib, lzo, zstd): enabled by a simple mount option.
  • Checksums on data and metadata: detection of silent corruption on read.
  • Scrub: integrity check of the whole volume, run on demand or scheduled.
  • Subvolumes: each subvolume is managed like an independent file system (mount, snapshot, quota).
  • Snapshots: instant, uninterrupted capture of a subvolume.
  • Online resizing: you can grow or shrink a mounted volume.
  • Per-subvolume quotas (qgroups).
  • Online defragmentation with btrfs filesystem defragment.

Concrete benefits

In the field, these features translate into direct gains for the administrator:

  • space saved with transparent compression;
  • fast backups via snapshots and btrfs send/btrfs receive;
  • suited to containers and to environments that create and destroy a lot of data;
  • built-in features without stacking layers (RAID, LVM, snapshot tools).

Limits to know

No solution is perfect, and Btrfs requires knowing its weak spots before adopting it in production:

  • RAID 5/6 profiles are considered unstable by the project itself (the so-called write hole problem): do not use them in production, prefer RAID 1 or RAID 10.
  • CoW can slow down intensive random writes (databases, VMs) and fragments those files heavily.
  • Disk space management is less intuitive than with ext4: df can show misleading values, and a volume can end up "full" while space remains (metadata full).
  • Administration requires learning a dedicated command (btrfs) and its subcommands, where ext4 makes do with the classic tools.

For which uses?

The choice of a file system depends on the write profile and on the need for features. Btrfs is especially relevant for:

  • file servers with frequent snapshots;
  • development workstations that handle many containers;
  • backup systems, thanks to send/receive;
  • SSD disks, thanks to compression that reduces writes.

Btrfs combines flexibility, integrity and advanced features without stacking layers, but it requires a more rigorous handling than ext4. Let's see how to create it properly.

Create a Btrfs file system

Before enjoying Btrfs's advanced features, you have to format the storage medium. This can be done on a whole disk or a partition. Btrfs does not need LVM: it directly manages multiple volumes and RAID.

Prepare the storage medium

You can create a Btrfs system on:

  • a raw disk (/dev/sdb),
  • a partition (/dev/sdb1).

To list the available disks and spot the right device:

Terminal window
lsblk

If it is a new disk, create a partition table with fdisk, parted or gdisk:

Terminal window
sudo fdisk /dev/sdb

Then create a partition such as /dev/sdb1, to format with Btrfs. Check that it does appear with lsblk before going on: formatting the wrong device destroys its data without confirmation.

Format as Btrfs with mkfs.btrfs

The basic command is:

Terminal window
sudo mkfs.btrfs /dev/sdb1

A few useful options:

  • -L name: gives the file system a label;
  • -d profile: sets the storage profile of the data (single, raid1, etc.);
  • -m profile: sets the storage profile of the metadata;
  • -f: forces formatting, even if the device already holds a file system.

Complete example:

Terminal window
sudo mkfs.btrfs -L data_btrfs -m single -d single /dev/sdb1

To create a volume over several disks:

Terminal window
sudo mkfs.btrfs -L pool_btrfs /dev/sdb1 /dev/sdc1

Btrfs then assembles the disks into a single volume. With recent versions of btrfs-progs (measured with 6.14 on Debian 13), data is spread as single (concatenation, no redundancy) and metadata as raid1 (mirroring). To get real data redundancy, ask for it explicitly:

Terminal window
sudo mkfs.btrfs -L pool_btrfs -d raid1 -m raid1 /dev/sdb1 /dev/sdc1

Check the creation

Even before mounting the volume, check that the file system is properly created and that the profiles match what you asked for:

Terminal window
sudo btrfs filesystem show /dev/sdb1

The output must show the label, the UUID and the list of member devices. The detailed space breakdown (btrfs filesystem df, btrfs filesystem usage) will only be available once the volume is mounted.

Creating a Btrfs file system is fast, but the initial choices (RAID profiles, number of disks) strongly influence performance and reliability: better to set them at formatting time than to convert afterwards.

Mount a Btrfs file system

Once the Btrfs file system is created, you must mount it to use it. Mounting brings the partition or volume into the system tree, typically under /mnt or /srv. Btrfs being geared towards volume and subvolume management, a few specifics apply compared with ext4.

Mount a Btrfs system temporarily

Manual mounting is the natural first step: it lets you validate that the volume works before writing it into the persistent configuration. Three commands are enough:

  1. Create a mount point:
Terminal window
sudo mkdir -p /mnt/data
  1. Mount the file system:
Terminal window
sudo mount /dev/sdb1 /mnt/data
  1. Check that everything is in place:
Terminal window
findmnt /mnt/data

or:

Terminal window
df -hT /mnt/data

The type column must show btrfs. This mount is temporary: it disappears at the next reboot.

Mount by label or UUID

It is safer to mount a Btrfs volume by its label or its UUID, especially when several disks are present: /dev/sdX names can change from one boot to the next.

To find these identifiers:

Terminal window
sudo blkid /dev/sdb1

Examples:

  • Mount by label:
Terminal window
sudo mount -L data_btrfs /mnt/data
  • Mount by UUID (use the one shown by blkid):
Terminal window
sudo mount UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data

Automatic mount with /etc/fstab

To make a mount persistent across reboots, add it to /etc/fstab (the file that describes the mounts applied at boot). Example:

UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,compress=zstd 0 0

Explanation:

  • UUID: stable identifier of the file system;
  • /mnt/data: mount point;
  • btrfs: file system type;
  • defaults,compress=zstd: options (here, compression enabled);
  • 0 0: no backup with dump, no fsck check at boot (Btrfs does not use fsck).

Test the configuration without rebooting:

Terminal window
sudo mount -a
findmnt /mnt/data

If mount -a returns an error, fix the line before any reboot: an invalid fstab entry can block the server's boot.

Specific case: mount a subvolume

A Btrfs subvolume is an internal tree of the volume, which behaves like a file system in its own right. Create one:

Terminal window
sudo btrfs subvolume create /mnt/data/@home

You can then mount this subvolume directly (rather than the root of the volume):

Terminal window
sudo mount -o subvol=@home /dev/sdb1 /home

In /etc/fstab, that gives:

UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /home btrfs defaults,subvol=@home 0 0

With Btrfs, you think in subvolumes rather than partitions: a more flexible split, which becomes decisive for backups and snapshots. Mount options let you fine-tune the behaviour of each mount further.

Btrfs-specific mount options

The Btrfs file system offers many mount options to fine-tune its behaviour: compression, automatic defragmentation, subvolume management, or SSD optimisations. Knowing them well lets you adapt the volume to its real use.

Performance options

These four options cover most of the tuning of a Btrfs volume. The first two change the way data is written, the next two reduce useless work. When in doubt, compress=zstd and noatime form a safe starting point for most uses.

  • compress=zstd | lzo | zlib Enables transparent compression of files. Recommended: zstd, which combines speed and a good compression ratio.

    Example in /etc/fstab:

    UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,compress=zstd 0 0
  • autodefrag Enables automatic defragmentation on write, useful for small files modified often (SQLite databases, browsers). Avoid it on large files such as VM images.

    Example:

    UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,compress=zstd,autodefrag 0 0
  • noatime Prevents updating the access date of files (atime), which reduces writes. Especially useful with CoW, where every atime update triggers a metadata write.

    Example:

    UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,noatime 0 0
  • space_cache=v2 Speeds up mounts and allocations by keeping a cache of free space. It is the default behaviour of recent kernels: you normally do not have to specify it, but you will come across it in existing configurations.

SSD options

On an SSD, the stake is not raw speed but TRIM management: telling the disk which blocks have become free to preserve its performance and its lifetime. Two options come into play:

  • ssd Tells the file system it runs on an SSD, which adjusts the allocation strategy. Btrfs automatically detects most SSDs: this option is rarely needed, and it does not enable TRIM.

  • discard=async Enables online TRIM (release of unused blocks on the SSD side) asynchronously, without hurting performance.

    Example:

    UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,ssd,discard=async 0 0

The alternative, often preferable, is periodic TRIM with the systemd fstrim.timer timer, shipped with util-linux:

Terminal window
sudo systemctl enable --now fstrim.timer
systemctl list-timers fstrim.timer

You can also run a manual TRIM to check that the volume supports it:

Terminal window
sudo fstrim -v /mnt/data

Security and access control

These options are not specific to Btrfs, but they belong to any well-hardened mount:

  • nodev: forbids device files on the mounted volume;
  • nosuid: ignores SUID/SGID bits, which reduces the privilege escalation surface;
  • noexec: forbids running programs from the volume (useful on /tmp, /var/log, external disks).

Combined example for /tmp:

UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /tmp btrfs defaults,nodev,nosuid,noexec 0 0

Subvolume management

Two options designate the subvolume to mount. Every @/@home style scheme used by distributions that install their root on Btrfs goes through them:

  • subvol=name Mounts a specific subvolume instead of the root of the volume.

    Example:

    UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /home btrfs defaults,subvol=@home 0 0
  • subvolid=id Alternative by numeric identifier of the subvolume, rarely used by hand.

Disable Copy-on-Write: nodatacow

For workloads that constantly rewrite the same blocks (databases, VM images), CoW hurts performance and fragments the files. The nodatacow mount option disables it for the whole volume, but that is rarely what you want: the most common is to disable it per directory with the chattr +C attribute:

Terminal window
sudo chattr +C /mnt/data/vm

The attribute only applies to files created after it is set: set it on an empty directory, before putting files there. Check with:

Terminal window
lsattr -d /mnt/data/vm

Beware: disabling CoW also disables checksums and compression on those files. You trade integrity for performance, knowingly.

Summary of common options

This table recaps the options to know and the contexts where they bring a real gain:

OptionMain purposeRecommended for
compress=zstdReduce disk spaceAll systems
autodefragReduce fragmentationSmall files modified often
noatimeReduce useless writesHeavily loaded systems
discard=asyncOnline TRIMSSD disks
nodev,nosuidStrengthen security/tmp, /home, external disks
subvol=@homeMount a specific subvolumeSystems with snapshots

Choosing your mount options well guarantees a Btrfs volume that is performant, stable and suited to its use. What remains is knowing what to do when something goes wrong: that is the role of btrfs check and scrub.

Check and repair with btrfs check and scrub

Even though Btrfs includes many error-detection mechanisms, a file system remains vulnerable to power cuts, hardware failures and bugs. You must therefore know the checking and repair tools, and above all in which order to use them: misused, they can make a corruption worse.

When to use btrfs check?

btrfs check analyses the internal structure of the file system (trees, metadata, connectivity). It is used:

  • after a crash or a sudden stop, if the volume refuses to mount;
  • in case of abnormal behaviour: missing files, repeated errors in the logs;
  • for a one-off manual check, volume unmounted.

Beware: btrfs check is only used on an unmounted file system. Never run it on a mounted volume.

Check without modifying

By default, btrfs check works read-only: it reports errors without touching anything. It is always the first step:

Terminal window
sudo btrfs check /dev/sdb1

An output with no error reported ends with a summary of the bytes checked. If errors appear, do not rush to repair: start by backing up what can be.

--repair: the last resort

The repair mode exists, but the upstream documentation is explicit: it is dangerous and must not be used without prior analysis of the errors detected. An ill-suited repair can make a volume permanently unrecoverable.

Terminal window
sudo btrfs check --repair /dev/sdb1

Before getting there, exhaust the less risky options:

  1. mount the volume read-only and copy the data elsewhere;
  2. try btrfs restore (extraction of files from an unmountable volume, without modifying it);
  3. look up the exact error message in the Btrfs documentation or mailing lists.

Only use --repair as a last resort, on a volume whose data is already backed up or lost anyway.

Scrub: check data online

Unlike check, scrub works on a volume that is mounted and in service. It reads every block, checks the checksums and automatically fixes errors when a healthy copy exists (RAID 1/10 profiles, metadata in dup).

Start a scrub (it goes to the background):

Terminal window
sudo btrfs scrub start /mnt/data

Follow the progress and the number of errors found:

Terminal window
sudo btrfs scrub status /mnt/data

A scheduled scrub (monthly, for instance) is the best defence against silent corruption: it detects damaged blocks before you need them.

Recover a corrupted system

If the volume that refuses to mount is the root system, the procedure goes through an external medium. The order of operations matters: you back up first, repair next.

  1. Boot from a Linux live USB with Btrfs support.
  2. Identify the partition with lsblk.
  3. Try a read-only mount and copy the data:
Terminal window
sudo mount -o ro /dev/sdb1 /mnt
  1. If the mount fails, check without modifying:
Terminal window
sudo btrfs check /dev/sdb1
  1. Only as a very last resort, once the data is extracted or lost:
Terminal window
sudo btrfs check --repair /dev/sdb1

Monitor and optimise a Btrfs volume

Btrfs is not a file system you format then forget. It offers a range of built-in tools to monitor its state, manage space, defragment and adjust its settings to the use. Here is how to keep an eye on it day to day.

Show file system information

To list Btrfs volumes and their devices:

Terminal window
sudo btrfs filesystem show

To show the split of space between data and metadata:

Terminal window
sudo btrfs filesystem df /mnt/data

Example output:

Data, single: total=10.00GiB, used=7.50GiB
Metadata, single: total=1.00GiB, used=512.00MiB
System, single: total=32.00MiB, used=16.00MiB

This data / metadata split is specific to Btrfs: each category has its own allocated space, and one can fill up before the other. For a more complete view (allocated space, unallocated, estimate of the real free space), prefer:

Terminal window
sudo btrfs filesystem usage /mnt/data

It is this command you must look at when df -h shows values that seem inconsistent: with CoW, compression and RAID, the classic df only tells part of the story.

Analyse and defragment

Copy-on-Write naturally fragments files modified in place. To analyse the number of extents (fragments) of a file:

Terminal window
sudo filefrag -v /mnt/data/fichier

To defragment a directory recursively:

Terminal window
sudo btrfs filesystem defragment -r /mnt/data

The -czstd option (or -clzo, -czlib) applies on-the-fly compression during defragmentation, handy to compress data written before compress=zstd was enabled:

Terminal window
sudo btrfs filesystem defragment -r -czstd /mnt/data

Trap to know: defragmentation breaks the links shared with snapshots and reflink copies. Each defragmented file becomes an independent copy again, which can make the space used explode on a volume rich in snapshots. Check the available space before and after with btrfs filesystem usage.

Watch errors and logs

Btrfs reports its errors in the kernel logs. Two commands bring them up:

Terminal window
sudo dmesg | grep -i btrfs
journalctl -k | grep -i btrfs

Btrfs also keeps per-device error counters (write, read, checksum errors), precious to spot a failing disk before the outage:

Terminal window
sudo btrfs device stats /mnt/data

Counters that grow from one check to the next signal a disk to replace.

Schedule a regular scrub

A monthly scrub detects silent corruption before it becomes data loss. With cron, add an entry in /etc/crontab:

0 3 1 * * root btrfs scrub start /mnt/data

You can also automate it cleanly with a systemd timer, which offers built-in logging. In both cases, check the result afterwards:

Terminal window
sudo btrfs scrub status /mnt/data

Resize a file system

Btrfs lets you grow or shrink a volume online, that is while it is mounted (it is even an obligation: the command works on the mount point):

  • Grow by 10 GiB:
Terminal window
sudo btrfs filesystem resize +10G /mnt/data
  • Shrink by 5 GiB:
Terminal window
sudo btrfs filesystem resize -5G /mnt/data
  • Set an absolute size:
Terminal window
sudo btrfs filesystem resize 100G /mnt/data

Check the result with btrfs filesystem usage /mnt/data. Beware: resizing the file system does not resize the underlying partition, which is managed separately (parted, growpart).

Manage quotas

Btrfs quotas (qgroups) limit space consumption per subvolume, very useful to isolate /home, /var or project directories. Enable them first:

Terminal window
sudo btrfs quota enable /mnt/data

Then look at usage per subvolume:

Terminal window
sudo btrfs qgroup show /mnt/data

And set a limit on a given subvolume:

Terminal window
sudo btrfs qgroup limit 50G /mnt/data/@home

Know that qgroups add a computing overhead, especially on volumes with many snapshots: only enable quotas if you need them.

Snapshots with Btrfs

One of Btrfs's major assets is creating instant snapshots. A snapshot is a frozen copy of a subvolume at a given moment, which only consumes space as changes happen (thanks to CoW). It is the ideal tool for backups, tests and quick rollbacks.

Create a snapshot

A snapshot is taken on a source subvolume. If needed, create one:

Terminal window
sudo btrfs subvolume create /mnt/data/@home

To create a read/write snapshot:

Terminal window
sudo btrfs subvolume snapshot /mnt/data/@home /mnt/data/@home_snap

For a read-only snapshot (mandatory for export with btrfs send, and ideal for a backup):

Terminal window
sudo btrfs subvolume snapshot -r /mnt/data/@home /mnt/data/@home_ro_snap

List existing snapshots

A snapshot is a subvolume like any other: the same command lists both and lets you check that the creation worked:

Terminal window
sudo btrfs subvolume list /mnt/data

Each line shows the identifier and the path of the subvolume. Each snapshot is independent: you can mount it, export it or delete it without touching the source.

Mount a snapshot

To look at the content of a snapshot (to recover a deleted file, for instance), mount it like any subvolume:

Terminal window
sudo mkdir -p /mnt/snap_home
sudo mount -o subvol=@home_ro_snap /dev/sdb1 /mnt/snap_home

Check with findmnt /mnt/snap_home that the mount is active, then copy the files you need.

Delete a snapshot

Snapshots pile up fast and hold on to disk space: old blocks are only freed when no snapshot references them any more. Delete those that are no longer used:

Terminal window
sudo btrfs subvolume delete /mnt/data/@home_snap

The operation is irreversible: list the subvolumes again afterwards to confirm the deletion.

Back up with btrfs send and btrfs receive

The send/receive pair exports a read-only snapshot as a stream, to store in a file or to send to another Btrfs volume (including via SSH). It is the basic building block of Btrfs backups.

Export a snapshot to a file:

Terminal window
sudo btrfs send /mnt/data/@home_ro_snap > backup-home.btrfs

Import it again on another mounted Btrfs volume:

Terminal window
sudo btrfs receive /mnt/backup < backup-home.btrfs

For incremental backups, the -p option only sends the difference between two snapshots:

Terminal window
sudo btrfs send -p /mnt/data/@home_ro_snap /mnt/data/@home_ro_snap2 > diff.btrfs

Practical use cases

Snapshots change the way you work day to day: any risky operation can be preceded by a return point that costs a few seconds. Typical examples:

  • before a system update, a read-only snapshot of the root;
  • daily backup of /home combined with send -p to an external disk;
  • before a configuration test or running a dubious script;
  • quick return to the previous state in a few seconds, without a full restore.

Btrfs-specific good practices

Even though Btrfs is a modern, feature-rich file system, its initial configuration and its day-to-day management make all the difference. Here are the practices that improve its reliability, performance and resilience over time.

Use subvolumes from the start

Rather than storing everything at the root of the volume, create subvolumes for /home, /var, /srv, etc. This split costs nothing at creation and opens up every feature per scope:

Terminal window
sudo btrfs subvolume create /mnt/data/@home
sudo btrfs subvolume create /mnt/data/@var

Benefits:

  • mount each directory independently, with its own options;
  • create targeted snapshots (snapshot /home without taking /var);
  • simplify incremental backups with btrfs send -p.

Enable transparent compression

Compression reduces the disk space used and often decreases I/O (fewer bytes written). Add the compress=zstd option in /etc/fstab:

UUID=0b3f2a17-6f4d-4c8a-9a6e-3d2f1e5c7b90 /mnt/data btrfs defaults,compress=zstd 0 0

It only applies to new writes. To recompress existing files:

Terminal window
sudo btrfs filesystem defragment -r -czstd /mnt/data

Reminder of the trap seen above: on a volume with snapshots, this defragmentation duplicates the shared data.

Schedule a regular scrub

Scrub is your silent-corruption detector. Run regularly (monthly, for instance, via cron or a systemd timer), it checks all the checksums while the volume stays in service:

Terminal window
sudo btrfs scrub start /mnt/data

Then look at btrfs scrub status /mnt/data: a non-zero error counter deserves immediate investigation (kernel logs, btrfs device stats).

Isolate write-intensive workloads

For databases and VM images, Copy-on-Write hurts performance and fragments files. Disable it on a dedicated directory, before creating the files in it:

Terminal window
sudo mkdir /mnt/data/vm
sudo chattr +C /mnt/data/vm
lsattr -d /mnt/data/vm

The lsattr output must show the C attribute. Keep the trade-off in mind: no more checksums nor compression on those files.

Enable and monitor quotas

On a volume shared between several uses, qgroups keep one subvolume from starving the others:

Terminal window
sudo btrfs quota enable /mnt/data
sudo btrfs qgroup show /mnt/data

Then set per-subvolume limits with btrfs qgroup limit, and keep in mind their overhead on heavily snapshotted volumes.

Document the configuration

A well-administered Btrfs volume is a volume whose configuration can be found again after a disaster. Write down in your infrastructure documentation:

  • UUID and labels of the volumes;
  • subvolumes created and their role;
  • mount options (compress, noatime, etc.);
  • snapshot policy (tool, frequency, retention);
  • quotas set.

It saves precious time during restores and migrations.

Check the system logs regularly

Btrfs reports its problems in the kernel logs well before the outright failure. Get into the habit of checking:

Terminal window
journalctl -k | grep -i btrfs
sudo btrfs device stats /mnt/data

You will thus spot in time the beginnings of corruption or a disk whose error counters are climbing.

Troubleshooting

The most frequent Btrfs problems have well-identified causes, and often a simple fix, provided you do not reach for --repair as a first reflex. This table covers the most common symptoms:

SymptomLikely causeFix
No space left on device while df shows free spaceSpace fully allocated to chunks, metadata fullDiagnose with btrfs filesystem usage, then rebalance: sudo btrfs balance start -dusage=50 /mnt/data
df -h shows inconsistent valuesCoW, compression and RAID skew the classic calculationUse btrfs filesystem usage as the reference
Volume refuses to mount after a crashDamaged metadataMount read-only (mount -o ro), back up, then btrfs check without --repair
Slow writes on a VM or a databaseFragmentation due to CoWchattr +C on a dedicated directory (new files), possibly autodefrag
btrfs send: ERROR: subvolume … is not read-onlyThe snapshot is not read-onlyRecreate the snapshot with btrfs subvolume snapshot -r
Space is not freed after deleting filesSnapshots still reference the blocksList (btrfs subvolume list) and delete obsolete snapshots

For any diagnosis, start with these three commands, which give the real state of the volume:

Terminal window
sudo btrfs filesystem usage /mnt/data
sudo btrfs device stats /mnt/data
journalctl -k | grep -i btrfs

Key points

  • Btrfs relies on Copy-on-Write: stronger integrity, instant snapshots, but fragmentation on files rewritten in place.
  • Think in subvolumes from creation: they carry snapshots, quotas and independent mounts.
  • zstd compression is a near-free gain: enable it by default via compress=zstd in /etc/fstab.
  • df -h lies on Btrfs: the reference is btrfs filesystem usage.
  • A scheduled scrub detects silent corruption; btrfs device stats monitors disk health.
  • btrfs check --repair is dangerous and documented as such upstream: read-only first, backup next, repair as a last resort.
  • RAID 5/6 profiles remain unstable: in production, stick to RAID 1 or RAID 10.
  • For VMs and databases, disable CoW per directory (chattr +C), accepting the loss of checksums.

Knowledge check

Check that the essentials of this guide are acquired. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer

Is this project useful to you?

The guides, courses, quizzes and labs stay free. If you use them regularly, you can contribute to their upkeep and development.

Become a supporting member (new tab) One-time support (new tab) Learn more

Follow the project on LinkedIn