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.
Live and snap-1 both reference A, B, C and D. The snapshot already exists before this write.
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.
The system root. Its mount point is /, but its path inside Btrfs is /@.
- Subvolume ID
- 256
- Path
- /@
- Mount Point
- /
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.
# /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
Recommended Subvolume Layout
This is one possible layout, not a required naming scheme. The @ prefix has no special meaning to Btrfs.
| Internal path | Mount point | Snapshot boundary |
|---|---|---|
/@ | / | System files |
/@home | /home | User files |
/@snapshots | /.snapshots | Stored local snapshots |
/@var | /var | Variable application data |
/@var/log | /var/log | Logs, 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.
Six data extents, each referenced by the live subvolume.
- Allocated data extents
- 6
- Retained only by snapshots
- 0
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.
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.
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%
All extents are available. Fail a disk to trace which copies remain.
sudo mkfs.btrfs -d raid1 -m raid1 /dev/sda1 /dev/sdb1Authored 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.
# /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.
- Space Saved
- 68%
- Ratio
- 3.1x
mount -o compress=zstd:3 /dev/sda1 /mntAuthored 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.
# 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.
- Status
- Ready
- Progress
- 0/12 blocks
- Verified
- 0
- Errors
- 0
- Repaired
- 0
- Unrecoverable
- None
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.
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.
# 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
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:
# 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:
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.
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
| Mechanism | Btrfs | OpenZFS | ext4 |
|---|---|---|---|
| Normal write model | CoW, with NOCOW file options | CoW | In-place data updates with journaling |
| Native snapshots | Subvolume snapshots | Dataset snapshots | Requires another storage layer |
| Transparent compression | Supported | Supported | Not native |
| File-data checksums | Normally enabled; NOCOW exception | Normally enabled | Not general file-data protection |
| Redundant storage | Data and metadata profiles | Pool/vdev configuration | Requires 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.
Related concepts
Master ZFS filesystem with pooled storage, RAID-Z, snapshots, and checksums. Learn enterprise-grade data integrity on Linux.
Follow filesystem copy-on-write from a changed block to a committed root. Explore snapshot sharing, space reclamation, and the trade-offs in Btrfs and ZFS.
Explore ext4, the default Linux filesystem with journaling, extents, and proven reliability. Learn how ext4 protects your data.
Learn FAT32 and exFAT filesystems for cross-platform USB drives and SD cards. Understand file size limits and compatibility.
Follow a filesystem transaction from journal to checkpoint. Explore crash recovery, ext4 journal modes, and the limits of data durability.
Explore Linux filesystems through interactive visuals. Learn VFS, compare ext4 vs Btrfs vs ZFS, and understand file operations.
