Skip to main content

Btrfs: Modern Copy-on-Write Filesystem

Trace how Btrfs shares extents, creates snapshots, distributes copies, compresses writes, and repairs checksum errors when a good replica exists.

A filesystem built around shared extents

A file looks like a sequence of bytes to an application. Btrfs maps those bytes to extents, ranges of stored data described by metadata trees. More than one file or subvolume can reference the same extent. Updating one reference does not have to change the others.

That separation explains the features on this page: copy-on-write preserves an existing extent while a new version is written; snapshots retain references to older versions; redundancy supplies another copy when a device or checksum fails. Each solves a different problem. A snapshot cannot replace a backup, and a checksum cannot reconstruct data without a good copy.

The six figures below are authored teaching models. Their block labels, sizes and scan sequences illustrate the mechanisms; they are not filesystem traces or performance measurements.

Copy-on-Write: The Magic Behind Everything

With normal data copy-on-write enabled, Btrfs writes changed data into new space and updates the associated metadata. A snapshot continues to reference the previous extent. The old space becomes reclaimable only when no file, snapshot or other reference needs it.

How CoW Actually Works

Step through a write to B. Compare the live file's references with the snapshot's references, then look at the physical extents below them. The middle step separates writing B′ from committing the new mapping.

Copy-on-write of block B
State
Step 1 / 3

Live and snap-1 both reference A, B, C and D. The snapshot already exists before this write.

Live file references
References extent AReferences extent BReferences extent CReferences extent D
snap-1 references
References extent AReferences extent BReferences extent CReferences extent D
Physical data extents · each stored once
A
Live + snap-1
B
Live + snap-1
C
Live + snap-1
D
Live + snap-1
Live only / new writeShared with liveSnapshot only

Authored model of one write and its commit. Metadata tree updates and device flushes are omitted; without another reference, old B could be reclaimed.

The diagram assumes a snapshot already exists. CoW alone does not keep an accessible history of every write. Btrfs also CoWs metadata on the path to a changed tree node; it does not copy every tree node on every update. The Btrfs design notes describe these trees and extent references.

Why This Changes Everything

Sharing makes snapshots inexpensive to create, but it moves some cost to later writes and retained versions. Transaction commits keep the filesystem's metadata consistent across a crash; they do not make an arbitrary multi-write application operation atomic. Applications still need their normal durability and consistency mechanisms, including fsync where appropriate.

The next question is which files a snapshot includes. In Btrfs, that boundary is a subvolume.

Subvolumes: Filesystems Within a Filesystem

A subvolume has its own file hierarchy while sharing the filesystem's storage pool. Its internal path and its mount point are different things: /@home inside Btrfs can be mounted at /home in Linux.

Select a row to inspect those two paths and its mount command. Expand @var to see nested subvolumes. Top-level ID 5 is fixed; the other IDs in this example are illustrative.

Subvolume hierarchy
/dev/sda1 (Btrfs)
@

The system root. Its mount point is /, but its path inside Btrfs is /@.

Subvolume ID
256
Path
/@
Mount Point
/
Mount the selected subvolume
sudo mount -o subvol=@ /dev/sda1 /

Example IDs and paths; only top-level ID 5 is fixed. Mount targets must exist. Btrfs options such as compress and nodatacow are shared across the filesystem, not set independently by these mounts.

Why Subvolumes Matter

A snapshot includes one subvolume's files, but does not recursively include nested subvolumes. Keeping logs or home directories in separate subvolumes lets a root snapshot leave those areas outside its restore boundary.

Most Btrfs-specific mount options, including compress, nodatacow and nodatasum, apply to the whole filesystem. Mounting another subvolume with different options does not establish an independent compression or CoW policy. Generic VFS options such as noatime have different scope. See the mount-option documentation.

bash
# /mnt/top exposes the top-level subvolume of an existing filesystem.
sudo mkdir -p /mnt/top /mnt/projects
sudo mount -o subvolid=5 /dev/sda1 /mnt/top
sudo btrfs subvolume create /mnt/top/projects
sudo mount -o subvol=projects /dev/sda1 /mnt/projects
sudo btrfs subvolume list /mnt/top

This is one possible layout, not a required naming scheme. The @ prefix has no special meaning to Btrfs.

Internal pathMount pointSnapshot boundary
/@/System files
/@home/homeUser files
/@snapshots/.snapshotsStored local snapshots
/@var/varVariable application data
/@var/log/var/logLogs, excluded from an @var snapshot

Snapshots: Time Travel for Your Data

A snapshot starts as another subvolume sharing the source's extents. Creating it needs metadata work and may need to flush pending writes, but it does not copy all file data. Subsequent changes let the two views diverge.

Step through two writes and two snapshots. After restoring the older state, notice why the newer extents still occupy space. Delete the last snapshot that references them to see when they become reclaimable.

Snapshot timeline
Step 1 / 7
Live subvolume

Six data extents, each referenced by the live subvolume.

Allocated data extents
6
Retained only by snapshots
0
Live subvolume references
References extent AReferences extent BReferences extent CReferences extent DReferences extent EReferences extent F
Physical data extents · each stored once
A
Live
B
Live
C
Live
D
Live
E
Live
F
Live
Live only / new writeShared with liveSnapshot only

Authored example with equal-size extents. Counts exclude metadata and redundancy; restoring here models a deliberate replacement, not an automatic boot rollback.

Snapshot Magic Explained

A snapshot preserves a view, not another physical copy of every byte. Corruption of a shared extent can affect both views. An independent backup protects against failures of this shared storage; snapshot retention only preserves selected earlier states.

The commands below assume the projects subvolume from the preceding example. A read-only snapshot can be inspected directly. Making a writable clone at a new path lets you inspect a recovery candidate without deleting the current subvolume.

bash
sudo mkdir -p /mnt/top/snapshots
sudo btrfs subvolume snapshot -r \
  /mnt/top/projects /mnt/top/snapshots/projects-before-change

# Create a writable recovery candidate at a new path.
sudo btrfs subvolume snapshot \
  /mnt/top/snapshots/projects-before-change /mnt/top/projects-recovered

sudo btrfs subvolume list -s /mnt/top

Changing which subvolume serves / also involves the distribution's boot and mount configuration. A filesystem snapshot alone does not guarantee a transactionally consistent database snapshot; coordinate application state when that matters.

Automated Snapshots with Snapper

Tools such as Snapper and btrbk can manage creation and retention. Their configuration depends on the distribution and subvolume layout. Decide what should be snapshotted, how long old versions should remain, and where independent backups go before enabling a schedule. The Btrfs subvolume documentation explains the sharing and nesting boundaries.

Built-in RAID: Redundancy Without mdadm

Btrfs chooses allocation profiles separately for data and metadata. single keeps one copy of an extent; RAID 0 stripes without redundancy; RAID 1 stores two copies on different devices. Adding a third device to RAID 1 does not create a third copy of every extent. RAID 10 combines striping with two copies.

Select a profile and fail individual disks. In the four-device RAID 10 illustration, losing disks 1 and 3 leaves a copy of every extent; losing disks 1 and 2 loses both copies of one stripe. Actual allocation varies across block groups, so surviving this small example is not a guarantee for an entire filesystem.

Btrfs RAID layouts
Profile

Two copies on different devices, even when a filesystem has more than two devices.

Devices in this example
2
Copies of each extent
2
Ideal data capacity
50%
Or select individual disks to fail or restore them.

All extents are available. Fail a disk to trace which copies remain.

Create RAID 1 on disposable devices
sudo mkfs.btrfs -d raid1 -m raid1 /dev/sda1 /dev/sdb1

Authored data layout with equal-size devices. Capacity excludes metadata and allocation overhead. Real placement varies by block group; the diagram is not a speed benchmark. mkfs creates a new filesystem on the named devices.

Creating Multi-Device Filesystems

The mkfs.btrfs commands in the figure create a new filesystem. Use only disposable devices intended for formatting. Capacity percentages assume equal-size devices and omit metadata and allocation overhead; they are not speed predictions.

For an existing filesystem, adding a device makes capacity available. A balance with conversion filters rewrites eligible block groups into the requested profile. It requires enough free space and enough devices for that profile.

bash
# /dev/sdc is an unused device intended for this filesystem.
sudo btrfs device add /dev/sdc /mnt
sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt
sudo btrfs filesystem usage /mnt

Btrfs also supports RAID1C3 and RAID1C4 for three and four copies. The profile reference documents supported device counts, including newer kernels' reduced minimums for RAID 0 and RAID 10. It warns against production use of RAID 5/6 because of known problems.

Transparent Compression: More Space, Often Faster

Compression reduces the bytes stored for compressible extents. Btrfs compresses writes and decompresses reads transparently; less device I/O can help some workloads, while compression also consumes CPU. A speedup depends on the data, level, hardware and workload.

Compare the authored size examples for text and already-compressed media. Algorithm selection highlights the corresponding result and mount option. These numbers teach the space calculation, not an expected compression ratio.

Compression by algorithm (illustrative values)
File Type
Algorithm
Text/Code: Source code, logs, configs
None1000 KB →1000 KB
100% of original
LZO1000 KB →450 KB-55%
45% of original
Zlib1000 KB →350 KB-65%
35% of original
Zstd:11000 KB →380 KB-62%
38% of original
Zstd:31000 KB →320 KB-68%
32% of original
Zstd:91000 KB →280 KB-72%
28% of original
Zstd:151000 KB →260 KB-74%
26% of original
Zstd:3
Level 3 is the default when zstd is selected
Space Saved
68%
Ratio
3.1x
Example mount option
mount -o compress=zstd:3 /dev/sda1 /mnt

Authored sizes for comparison, not results from compressing files. Ratios and CPU cost depend on the input, level and implementation; no throughput is measured here. Mount options affect newly written data across this filesystem.

Compression Algorithms

Btrfs supports zlib, LZO and zstd. LZO has no level parameter; zlib and zstd offer levels that trade CPU work against size. Selecting zstd without a level uses level 3. That is a default within zstd, not a claim that every Btrfs filesystem has compression enabled. See the compression reference.

bash
# Enable zstd for newly written data.
sudo mount -o compress=zstd:3 /dev/sdb1 /mnt

# Inspect actual compression if the separate compsize tool is installed.
sudo compsize /mnt

# Rewrite existing data with compression. This can break extent sharing.
sudo btrfs filesystem defragment -r -czstd /mnt/projects

A mount option does not recompress existing data. Balance preserves file extents rather than recompressing them. Defragmentation can rewrite them, but may increase space use when snapshots or reflinks were sharing the old extents.

When NOT to Compress

Already-compressed or encrypted data often saves little. Btrfs uses heuristics to avoid unhelpful compression attempts. compress-force bypasses that heuristic; it does not force an expanded result to be stored as compressed data.

Disabling CoW is a separate workload decision, not just a compression switch. A NOCOW file also loses data checksums and compression. This changes what the next mechanism, scrubbing, can verify.

Data Integrity: Checksums and Self-Healing

Btrfs normally checksums file data and metadata. CRC32C is the default checksum algorithm; other algorithms can be selected when creating the filesystem. NOCOW/NODATASUM file data is an exception, although its metadata remains protected.

A checksum mismatch detects damage. Repair additionally needs a readable copy that passes verification. Play the scrub with and without a healthy mirror, then disable simulated corruption to compare the outcome.

Scrub and repair
Step 1 / 18
Status
Ready
Progress
0/12 blocks
Verified
0
Errors
0
Repaired
0
Unrecoverable
None
#0
config.txt
Hash:—
#1
data.db
Hash:—
#2
photo.jpg
Hash:—
#3
notes.md
Hash:—
#4
app.bin
Hash:—
#5
log.txt
Hash:—
#6
config.txt
Hash:—
#7
data.db
Hash:—
#8
photo.jpg
Hash:—
#9
notes.md
Hash:—
#10
app.bin
Hash:—
#11
log.txt
Hash:—
VerifiedCorruptRepaired from mirror

Authored scan of twelve checksummed blocks. Hashes are toy identifiers, not CRC32C; the mirror is assumed healthy. NOCOW file data lacks checksum protection and is outside this model.

The Power of Scrubbing

Scrub visits allocated data and metadata, checks supported checksums and reports read errors. On a writable filesystem with replicated extents, it can replace damaged contents with a verified good copy. A second copy is not useful if it is also corrupt.

bash
sudo btrfs scrub start /mnt
sudo btrfs scrub status /mnt
sudo btrfs device stats /mnt

Checksum Protection

The demo assumes two known-good replicas before corruption is introduced. Real repair depends on the allocation profile and the copies that remain readable. DUP can provide two copies on one device, but cannot protect against losing that device. Scrub is not a complete filesystem consistency checker and cannot validate NOCOW file contents through missing data checksums. The scrub documentation describes these limits.

Creating and Managing Btrfs

Creating a Btrfs Filesystem

This example formats a disposable partition, mounts it, then inspects its allocation. discard is a mount option, not a mkfs.btrfs -O filesystem feature.

bash
# Creates a new filesystem on the named partition.
sudo mkfs.btrfs -L DataDrive /dev/sdb1
sudo mkdir -p /mnt/data
sudo mount -o compress=zstd:3 /dev/sdb1 /mnt/data
sudo btrfs filesystem usage /mnt/data

Essential Mount Options

Start with distribution defaults and add options for a specific need. For example, compress=zstd:3 requests compression of new writes. noatime changes access-time semantics. SSD detection, discard and free-space handling depend on the kernel and device; avoid copying a universal “optimal” option list without checking the mount reference.

Maintenance Commands

bash
sudo btrfs filesystem usage /mnt
sudo btrfs device usage /mnt
sudo btrfs balance status /mnt

# Example targeted balance: process metadata groups below 50% usage.
# Use after inspecting allocation; balance itself needs working space.
sudo btrfs balance start -musage=50 /mnt

A full balance can move a large amount of data. It is not required as routine cleanup after every snapshot or write. Read the balance documentation before choosing conversion or usage filters.

Common Pitfalls and Solutions

1. "No Space Left" with Plenty of Free Space

File-visible free space is only part of the picture. Data and metadata block groups, profile constraints and device allocation all affect whether a new write can proceed. Inspect btrfs filesystem usage and btrfs device usage first. Deleting unneeded snapshots may free retained extents after cleanup; a targeted balance may help some allocation problems but can itself fail for lack of workspace.

2. RAID 5/6 Data Loss

Do not treat all profiles as equally mature. Check the current Btrfs feature status and profile documentation when designing an array. The diagrams here cover single, RAID 0, RAID 1 and RAID 10, and do not model parity recovery.

3. Slow Performance with Databases/VMs

Repeated random overwrites can incur CoW allocation and fragmentation costs. Measure the actual workload before changing policy. For a newly created empty directory, chattr +C makes newly created files inherit NOCOW:

bash
# Use a new, empty directory before creating the workload's files.
sudo mkdir /mnt/data/vm-images-new
sudo chattr +C /mnt/data/vm-images-new

This also disables data checksums and compression for those files. It does not convert existing file extents in place. Snapshot sharing can still require CoW to preserve an older version; metadata remains CoW. A per-subvolume nodatacow mount is not an isolated policy.

4. Snapshot Space Explosion

Deleting a live file does not free extents retained by a snapshot. Keep a retention policy and account for delayed snapshot cleanup. Delete only an identified snapshot you no longer need:

bash
sudo btrfs subvolume list -s /mnt/top
sudo btrfs subvolume delete /mnt/top/snapshots/old-snapshot

5. Can't Delete Subvolume

Check for mounted or nested subvolumes and inspect the reported error. Nested subvolumes are separate objects; list them before deliberately deleting children and then their parent. Do not assume deleting a parent is recursive.

bash
sudo btrfs subvolume list -o /mnt/top/target

Performance Tuning

Measure the operation that matters: random-write latency, sequential throughput, CPU use or space consumption. Record the kernel, device, mount options, compression level, snapshot retention and measurement boundary. Changing one variable at a time makes the result interpretable. The figures on this page provide no measured performance evidence.

Btrfs vs ZFS vs ext4

MechanismBtrfsOpenZFSext4
Normal write modelCoW, with NOCOW file optionsCoWIn-place data updates with journaling
Native snapshotsSubvolume snapshotsDataset snapshotsRequires another storage layer
Transparent compressionSupportedSupportedNot native
File-data checksumsNormally enabled; NOCOW exceptionNormally enabledNot general file-data protection
Redundant storageData and metadata profilesPool/vdev configurationRequires another storage layer

The OpenZFS concepts and ext4 design documentation describe the other implementations. This compares mechanisms rather than assigning fixed RAM requirements or universal performance rankings. For the surrounding layers, continue with filesystems, copy-on-write and ZFS.

When to choose Btrfs (and when ext4, XFS, or ZFS is the better answer)

Btrfs fits systems that benefit from independently managed subvolumes, local snapshots, transparent compression and checksummed storage. Plan snapshot retention, independent backups and redundancy together; no one feature supplies all three.

For write-heavy databases or VM images, compare the intended filesystem and configuration using the real workload. ext4 or XFS can be a simpler choice when those Btrfs features are unnecessary. OpenZFS is another option when dataset management and its pool model match the requirements. Neither storage capacity nor a single RAM threshold decides the choice by itself.

The central question is now concrete: which references preserve an old version, which devices hold another copy, and what evidence tells you that copy is good? Those are separate responsibilities even when one filesystem implements them.

If you found this explanation helpful, consider sharing it with others.

Mastodon