Btrfs Deep Dive: Copy-on-Write, Snapshots, and Modern Storage

Introduction

Btrfs (B-tree File System) represents one of the most ambitious filesystem projects in the Linux ecosystem. Developed initially by Oracle in 2007 and now maintained by a broad community of contributors, Btrfs was designed from the ground up to address the limitations of traditional Linux filesystems while providing enterprise-grade features previously only available in expensive proprietary solutions. In 2026, Btrfs has matured significantly, becoming the default filesystem for major distributions like openSUSE and Fedora, and offering capabilities that rival Sun’s ZFS.

This comprehensive guide explores Btrfs in depth, covering its architecture, core features including copy-on-write, snapshots, and subvolumes, RAID configurations, compression options, and data integrity mechanisms. Whether you’re evaluating Btrfs for a new deployment, migrating from ext4, or troubleshooting an existing Btrfs setup, this article provides the knowledge you need to leverage Btrfs effectively.

Understanding Btrfs Architecture

Btrfs introduces a fundamentally different approach to filesystem design compared to traditional Linux filesystems. Rather than treating the filesystem as a simple layer for storing and retrieving data, Btrfs implements an integrated approach that combines filesystem and volume management capabilities traditionally handled by separate technologies like LVM.

B-Tree Data Structure

At the heart of Btrfs lies the B-tree data structure, from which the filesystem derives its name. Unlike the inode-based structure of ext4, Btrfs uses extent-based storage where file data is tracked in B-trees, enabling efficient handling of large files and directories while providing excellent scalability.

# Check filesystem structure
btrfs inspect-internal dump-tree /dev/sda1 | head -100

# View filesystem info
btrfs filesystem show /dev/sda1
# Label: none
#   uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   Total devices 1 FS bytes used 256.00GiB
#   devid 1 size 512.00GiB used 256.00GiB path /dev/sda1

Copy-on-Write (COW)

The copy-on-write mechanism is the foundation of Btrfs’s capabilities. When modifying existing data, Btrfs does not overwrite the original data in place. Instead, it writes the modified data to new locations and updates the filesystem metadata to point to the new data. This approach provides several critical benefits:

Crash Consistency: If the system crashes during a write operation, the original data remains intact
Efficient Snapshots: Creating a snapshot is instantaneous because it only copies metadata
Data Integrity: Both data and metadata have checksums, allowing detection of corruption

# Demonstrate COW behavior
# Create a file
echo "original content" > /mnt/btrfs/test.txt

# Check extent information
filefrag -v /mnt/btrfs/test.txt
# Filesystem stores data in extents, not individual blocks

# Modify the file
echo "modified content" >> /mnt/btrfs/test.txt

# Original data remains until garbage collection
# View reflinks (COW copies)
ls -la /mnt/btrfs/
cp --reflink /mnt/btrfs/test.txt /mnt/btrfs/test_copy.txt

Btrfs On-Disk Structure

┌─────────────────────────────────────────────────────────────────────┐
│                      BTRFS ON-DISK STRUCTURE                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Superblock (at multiple locations for redundancy)                  │
│  ├─ Primary superblock: offset 64K                                  │
│  └─ Backup copies: offset 64GB, 256GB, 1TB                        │
│                                                                      │
│  Chunk Tree                                                         │
│  ├─ Block group descriptors                                         │
│  ├─ Device layout                                                   │
│  └─ Stripe/mirror information                                       │
│                                                                      │
│  Trees (stored as extents)                                          │
│  ├─ Chunk Tree - Device allocation                                  │
│  ├─ Extent Tree - Data block allocation                            │
│  ├─ File Tree - Directory and file metadata                        │
│  ├─ Checksum Tree - Data checksums                                  │
│  └─ Device Tree - Multi-device information                         │
│                                                                      │
│  Block Groups                                                       │
│  ├─ Data - File data                                                │
│  ├─ Metadata - Btrfs internal structures                           │
│  └─ System - Chunk tree                                             │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Core Btrfs Features

Subvolumes

Subvolumes are one of Btrfs’s most powerful features, allowing you to create separate internal filesystem roots that can be mounted independently, snapshotted individually, and managed with different quotas. This capability is fundamental to Btrfs’s flexibility.

# Create a subvolume
btrfs subvolume create /mnt/btrfs/volumes/data

# List subvolumes
btrfs subvolume list /mnt/btrfs
# ID 256 gen 12345 top level 5 path volumes/data

# Create nested subvolume
btrfs subvolume create /mnt/btrfs/volumes/data/backups

# Delete a subvolume
btrfs subvolume delete /mnt/btrfs/volumes/data

# Mount specific subvolume
mount -o subvol=volumes/data /dev/sda1 /mnt/data

# Set default subvolume
btrfs subvolume set-default 256 /mnt/btrfs

# View subvolume info
btrfs subvolume show /mnt/btrfs/volumes/data

Subvolumes are essential for managing complex deployments:

# Example: Separate system and user data
# /etc/fstab example
# Root filesystem with default subvolume
/dev/sda1 /               btrfs defaults,subvol=@ 0 0
# Home as separate subvolume
/dev/sda1 /home           btrfs defaults,subvol=@home 0 0
# Snapshots excluded from rollbacks
/dev/sda1 /var/cache      btrfs defaults,subvol=@cache 0 0

Snapshots

Snapshots in Btrfs are read-write or read-only copies of subvolumes. Unlike traditional backup solutions that copy all data, Btrfs snapshots are instantaneous because they initially share the same data blocks as the original subvolume.

# Create read-only snapshot
btrfs subvolume snapshot -r /mnt/btrfs/volumes/data /mnt/btrfs/snapshots/data-$(date +%Y%m%d)

# Create read-write snapshot
btrfs subvolume snapshot /mnt/btrfs/volumes/data /mnt/btrfs/snapshots/data-dev

# List snapshots
btrfs subvolume list /mnt/btrfs -o
# Shows all subvolumes including snapshots

# Delete snapshot
btrfs subvolume delete /mnt/btrfs/snapshots/data-20260101

# Send/receive for backup
btrfs send /mnt/btrfs/snapshots/data-20260101 | ssh backup@server "btrfs receive /backup/"

Compression

Btrfs supports transparent compression, reducing storage requirements without application changes. Two compression algorithms are available: zlib (better compression) and lzo (faster compression).

# Mount with compression
mount -o compress=zstd /dev/sda1 /mnt/btrfs

# Or in /etc/fstab
# /dev/sda1 /mnt/btrfs btrfs compress=zstd,space_cache=v2 0 0

# Set compression per file
chattr +c /mnt/btrfs/largefile.log
# Remove compression
chattr -c /mnt/btrfs/largefile.log

# Check compression status
btrfs filesystem du /mnt/btrfs
# Shows size vs disk usage

# Use compact option
mount -o compress-force=zstd /dev/sda1 /mnt/btrfs
# Force compression even on incompressible data

Data Integrity and Checksumming

Btrfs provides end-to-end data integrity through checksums stored separately from data. Each extent has an associated checksum that is verified on read, ensuring detection of both media errors and silent data corruption.

# Enable scrubbing (full data verification)
btrfs scrub start /mnt/btrfs
# Or with compression
btrfs scrub start -c zstd /mnt/btrfs

# Check scrub status
btrfs scrub status /mnt/btrfs
# scrub status for a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   scrub started at Mon Mar  5 10:00:00 2026, finished after 10 minutes
#   total bytes scrubbed: 256.00GiB
#   error: 0
#   fixed: 0

# Enable error injection for testing
btrfs dev error -o 1000 /dev/sda1  # Inject every 1000 reads

# Check filesystem integrity
btrfs check --check-data-csum /dev/sda1

# View error stats
btrfs device stats /dev/sda1

Multi-Device Support and RAID

Unlike traditional filesystems that sit on top of block devices managed by LVM, Btrfs integrates volume management directly, supporting various RAID configurations natively.

Creating Multi-Device Filesystems

# Create filesystem with multiple devices
mkfs.btrfs -d raid1 -m raid1 /dev/sda1 /dev/sda2

# RAID options:
# -d (data): raid0, raid1, raid10, single, dup
# -m (metadata): raid0, raid1, raid10, single, dup

# Add device to existing filesystem
btrfs device add /dev/sdb1 /mnt/btrfs

# Remove device
btrfs device remove /dev/sdb1 /mnt/btrfs

# Balance to redistribute data
btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt/btrfs

RAID Configuration Details

# RAID1 - Mirroring
# Each block written to 2 devices
# Survives 1 disk failure
mkfs.btrfs -d raid1 -m raid1 /dev/sda1 /dev/sda2

# RAID10 - Striped Mirrors
# Combines striping and mirroring
# Requires at least 4 devices
mkfs.btrfs -d raid10 -m raid1 /dev/sda1 /dev/sda2 /dev/sdb1 /dev/sdb2

# RAID0 - Striping
# Performance only, no redundancy
# Use only for temp data
mkfs.btrfs -d raid0 -m single /dev/sda1 /dev/sda2

# Single/DUP - No redundancy
# dups (double copy) stores metadata twice on same device
mkfs.btrfs -d single -m dup /dev/sda1

Converting RAID Configurations

# Convert from single to RAID1
btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt/btrfs

# Convert RAID1 to RAID10
btrfs balance start -dconvert=raid10 -mconvert=raid1 /mnt/btrfs

# Monitor balance progress
btrfs balance status /mnt/btrfs

# Cancel balance
btrfs balance cancel /mnt/btrfs

Btrfs Administration

Filesystem Operations

# Resize filesystem
btrfs filesystem resize +50G /mnt/btrfs
btrfs filesystem resize -100G /mnt/btrfs
btrfs filesystem resize max /mnt/btrfs

# Defragment (online)
btrfs filesystem defrag -r /mnt/btrfs
# With compression
btrfs filesystem defrag -r -czstd /mnt/btrfs

# Show usage
btrfs filesystem df /mnt/btrfs
# Data, single: total=256.00GiB, used=128.00GiB
# Metadata, RAID1: total=8.00GiB, used=4.00GiB
# System, RAID1: total=32.00MiB, used=64.00KiB

# Detailed usage
btrfs filesystem usage /mnt/btrfs

# Label filesystem
btrfs filesystem label /mnt/btrfs mydata

Quota Groups (qgroups)

Btrfs supports quotas for subvolumes, enabling storage limits and reporting:

# Enable quotas
btrfs quota enable /mnt/btrfs

# Set quota for subvolume
btrfs qgroup limit 100G /mnt/btrfs/volumes/data

# Show quota usage
btrfs qgroup show /mnt/btrfs
# qgroupid         rfer         excl
# 0/256           50.00GiB     10.00GiB

# Set limit for path
btrfs qgroup limit -e 50G /mnt/btrfs/volumes/data
# -e excludes snapshots from limit

Device Management

# Replace failed device
btrfs replace start -f /dev/sdc1 /dev/sda1 /mnt/btrfs

# Scan for Btrfs devices
btrfs device scan

# Zero-free space (for SSD TRIM)
btrfs filesystem zero-log /dev/sda1

# Rescue commands
btrfs rescue super-recover /dev/sda1
btrfs rescue chunk-recover /dev/sda1
btrfs rescue zero-log /dev/sda1

Performance Optimization

Mount Options

# /etc/fstab optimized options
# For SSDs
/dev/sda1 /mnt/btrfs btrfs defaults,ssd,discard=async,space_cache=v2,compress=zstd 0 0

# For HDDs
/dev/sda1 /mnt/btrfs btrfs defaults,space_cache=v2,compress=zstd 0 0

# For maximum performance (no features)
/dev/sda1 /mnt/btrfs btrfs defaults,nospace_cache,noatime 0 0

# Options explained:
# ssd              - SSD optimization
# discard=async   - Async TRIM
# space_cache=v2   - Free space caching
# compress=zstd   - Transparent compression
# noatime          - Don't update access times
# nodatacow       - Disable COW for performance (not for snapshots)
# nodatasum       - Disable checksumming (not recommended)

Space Cache

# Enable free space cache (recommended)
mount -o space_cache=v2 /dev/sda1 /mnt/btrfs

# Convert free space cache
btrfs balance start -musage=5 /mnt/btrfs
# Forces recreation of space cache

Nocow Mode

For databases and certain workloads, COW can introduce overhead. The nodatacow option disables copy-on-write for new data:

# Mount with nocow
mount -o nodatacow /dev/sda1 /mnt/btrfs

# For specific file (must be empty or new)
touch /mnt/btrfs/database/file
chattr +C /mnt/btrfs/database/file
btrfs filesystem defrag /mnt/btrfs/database/file

# WARNING: nodatacow disables:
# - Snapshots for affected files
# - Data checksumming
# - Compression

Troubleshooting

Common Issues and Solutions

# Issue: Filesystem won't mount (readonly)
# Cause: Previous mount failed or filesystem error
mount -o ro,recovery /dev/sda1 /mnt/btrfs

# Issue: Disk space shows but cannot allocate
# Cause: Metadata exhaustion
btrfs balance start -dusage=0 /mnt/btrfs

# Issue: Too many idle metadata chunks
btrfs balance start -dusage=95 /mnt/btrfs
btrfs balance start -musage=95 /mnt/btrfs

# Issue: Transaction aborted
# Check forENOSPC (no space) issues
dmesg | grep -i btrfs

# Fix: Delete old snapshots
btrfs subvolume delete $(btrfs subvolume list /mnt/btrfs | grep snapshot)

# Issue: Disk failure in RAID1
# Replace device
btrfs device replace start /dev/sdb1 /dev/sdc1 /mnt/btrfs

Recovery Procedures

# Unmount filesystem
umount /dev/sda1

# Check filesystem
btrfs check --readonly /dev/sda1

# If check fails, try recovery
btrfs check --recovery /dev/sda1

# Rebuild header
btrfs rescue super-recover /dev/sda1

# Rebuild chunk tree
btrfs rescue chunk-recover /dev/sda1

# Fix transmission issues
btrfs rescue zero-log /dev/sda1

# After recovery, run scrub
btrfs scrub start /dev/sda1

Monitoring and Maintenance

# Regular health check
btrfs device stats /dev/sda1

# Weekly scrub (cron)
# 0 3 * * 0 btrfs scrub start -B /mnt/btrfs

# Monitor space
watch -n 5 "btrfs filesystem df /mnt/btrfs"

# Check for errors
journalctl -k | grep -i btrfs | grep -i error

# Profile filesystem operations
btrfs profile command args

Use Cases

Container Storage

Btrfs excels for container workloads due to efficient snapshots and subvolumes:

# Optimized container storage
# /var/lib/docker on Btrfs
# Create subvolume per container
btrfs subvolume create /var/lib/docker/btrfs/subvolumes/container1
# Benefits: Instant snapshot for rollback, efficient storage

Backup and Recovery

# Daily snapshots with rotation
#!/bin/bash
DATE=$(date +%Y%m%d)
btrfs subvolume snapshot -r /data /snapshots/data-$DATE
# Keep 7 days
find /snapshots -maxdepth 1 -type d -name "data-*" -mtime +7 -exec btrfs subvolume delete {} \;
# Offsite backup
btrfs send /snapshots/data-$DATE | ssh backup "btrfs receive /backup/"

Database Storage

# Database on Btrfs considerations
# Use nodatacow for data files
mount -o nodatacow /dev/sdb1 /var/lib/postgresql
# Use COW for WAL and logs
mount -o compress=zstd /dev/sda1 /var/lib/postgresql/wal

Comparison with Other Filesystems

Feature	Btrfs	ext4	ZFS
Max Filesystem Size	16 EiB	1 EiB	256 ZiB
Max File Size	16 EiB	16 TiB	16 EiB
Copy-on-Write	Yes	No	Yes
Snapshots	Yes	No (via LVM)	Yes
Native RAID	Yes	No (mdadm)	Yes
Compression	Yes (zlib, lzo, zstd)	No	Yes
Data Checksums	Yes	Optional	Yes
Encryption	dm-crypt	dm-crypt	ZFS native
RAID Levels	0,1,10	0,1,5,6 (mdadm)	0,1,10,z2,z3

Conclusion

Btrfs represents a paradigm shift in Linux filesystem design, combining traditional filesystem capabilities with enterprise-grade features previously only available in specialized solutions. Its integrated approach to volume management, combined with copy-on-write semantics, makes it exceptionally well-suited for modern workloads requiring efficient snapshots, transparent compression, and built-in data integrity.

While Btrfs has matured significantly and is considered production-ready for most use cases, certain scenarios may still favor ext4 or ZFS. For desktop and server deployments where snapshot-based backups, compression, and data integrity are priorities, Btrfs offers an excellent balance of features and performance. The key to successful Btrfs deployment lies in understanding its strengths—particularly subvolumes, snapshots, and integrated RAID—while being aware of its requirements, including regular scrubs and proper sizing of metadata space.

As Linux continues evolving, Btrfs stands as a testament to what’s possible when filesystem development embraces modern design principles. Whether you’re building a backup system, container infrastructure, or simply seeking a robust desktop filesystem, Btrfs provides capabilities that justify its position as the successor to ext4.