Status

Overview

For a list of features by their introduction, please see Changes (feature/version).

The table below aims to serve as an overview for the stability status of the features BTRFS supports. While a feature may be functionally safe and reliable, it does not necessarily mean that its useful, for example in meeting your performance expectations for your specific workload. Combination of features can vary in performance, the table does not cover all possibilities.

The table is based on the latest released linux kernel: 6.8

The columns for each feature reflect the status of the implementation in following ways:

Stability - completeness of the implementation, use case coverage
Performance - how much it could be improved until the inherent limits are hit
Notes - short description of the known issues, or other information related to status

Legend:

OK: should be safe to use, no known major deficiencies
mostly OK: safe for general use, there are some known problems that do not affect majority of users
Unstable: do not use for other then testing purposes, known severe problems, missing implementation of some core parts

Feature	Stability	Performance	Notes
Subvolumes, snapshots	OK	OK
Compression	OK
Checksumming algorithms	OK	OK
Defragmentation	mostly OK		extents get unshared (see below)
Autodefrag (in Administration)	OK
Discard (synchronous)	OK		mounted with -o discard (has performance implications), also see fstrim
Discard (asynchronous)	OK		mounted with -o discard=async (improved performance)
Out-of-band dedupe	OK	mostly OK	(reflink), heavily referenced extents have a noticeable performance hit (see below)
File range cloning	OK	mostly OK	(reflink), heavily referenced extents have a noticeable performance hit (see below)
Filesystem resize	OK	OK	shrink, grow
Device replace	mostly OK	mostly OK	(see below)
Auto-repair	OK	OK	automatically repair from a correct spare copy if possible (DUP, RAID1, RAID10, RAID56)
Scrub	OK	OK
Scrub + RAID56	mostly OK	mostly OK
Degraded mount (in Administration)	OK	n/a
Balance	OK	OK	balance + qgroups can be slow when there are many snapshots
Send	OK	OK
Receive	OK	OK
Offline UUID change	OK	OK
Metadata UUID change	OK	OK
Temporary FSID	6.8	6.8	Single devices with same FSID can be mounted repeatedly, getting a temporary UUID.
Seeding	OK	OK
Quotas, qgroups	mostly OK	mostly OK	qgroups with many snapshots slows down balance
Squota, simplified qgroups	6.8	6.8	simplified qgroup accounting, better performance, specific use case
Swapfile	OK	n/a	with some limitations
nodatacow	OK	OK
Subpage block size	OK	OK	Also see table below for compatibility.
Zoned mode	mostly OK	mostly OK	Not yet feature complete but moderately stable, also see table below for compatibility.

Block group profiles

Feature	Stability	Performance	Notes
Single (block group profile)	OK	OK
DUP (block group profile)	OK	OK
RAID0	OK	OK
RAID1	OK	mostly OK	reading from mirrors in parallel can be optimized further (see below)
RAID1C3	OK	mostly OK	reading from mirrors in parallel can be optimized further (see below)
RAID1C4	OK	mostly OK	reading from mirrors in parallel can be optimized further (see below)
RAID10	OK	mostly OK	reading from mirrors in parallel can be optimized further (see below)
RAID56	unstable	n/a	(see below)
Mixed block groups	OK	OK

On-disk format

Features that are typically set at mkfs time (sometimes can be changed or converted later).

Feature	Stability	Performance	Notes
extended-refs	OK	OK	mkfs.btrfs default since 3.12
skinny-metadata	OK	OK	mkfs.btrfs default since 3.18
no-holes	OK	OK	mkfs.btrfs default since 5.15
Free space tree	OK	OK	mkfs.btrfs default since 5.15
Block group tree	OK	OK
Raid stripe tree	mostly OK	OK	not all profiles are supported and RST is behind CONFIG_BTRFS_DEBUG build option
Squota	OK	OK	Simplified tracking needs on-disk format update, but may work in a limited way without it.

Interoperability

Integration with other Linux features or external systems. See also.

Feature	Stability	Performance	Notes
NFS	OK	OK
cgroups	OK	OK	IO controller
io_uring	OK	OK
fsverity	OK	OK
idmapped mount	OK	OK
Samba	OK	OK	compression, server-side copies, snapshots

Please open an issue if:

there’s a known missing entry
a particular feature combination that has a different status and is worth mentioning separately
you know of a bug that lowers the feature status

Subpage block size

Most commonly used page sizes are 4KiB, 16KiB and 64KiB. All combinations with a 4KiB sector size filesystems are supported. Some features are not compatible with subpage or require another feature to work. Since btrfs-progs 6.7 the default sector size is 4KiB as this allows cross-architecture compatibility.

Feature	Status	Notes
Inline files	unsupported	The max_inline mount option value is ignored, as if mounted with max_inline=0
Free space cache v1	unsupported	Free space tree is mandatory, v1 makes some assumptions about page size
Compression	partial support	Only page-aligned ranges can be compressed
Sectorsize	supported	The list of supported sector sizes on a given version can be found in file `/sys/fs/btrfs/features/supported_sectorsizes`

Zoned mode

Features that completely incompatible with zoned mode are listed below. Compatible features may not be listed and are assumed to work as they are unaffected by the zoned device constraints.

Feature	Status	Notes
Boot	incompatible	The blocks where partition table is stored are used for super block
Mixed block groups	incompatible	Interleaving data and metadata would lead to out of order write
NODATACOW	incompatible	In-place overwrite
fallocate	incompatible	Preallocation of blocks would require an out of order write
Free space cache v1	incompatible	Cache data are updated in a NODATACOW-way
Swapfile	incompatible	Swap blocks are written out of order
Offline UUID change	incompatible	Metadata blocks are updated in-place
Free space tree	supported
Block group tree	supported
Raid stripe tree	supported	Allows to use RAID in zoned mode
Filesystem resize	supported
Balance	supported
Metadata UUID change	supported
RAID0, RAID1*	supported	requires raid-stripe-tree
RAID56	not implemented	Will be supported once raid-stripe-tree support is implemented
discard	not implemented	May not be required at all due to automatic zone reclaim
subpage blocksize	not implemented	Missing support for compressed data
fsverity	TBD
seeding	TBD

Details that do not fit the table

Defrag

The data affected by the defragmentation process will be newly written and will consume new space, the links to the original extents will not be kept. See also btrfs-filesystem(8) . Though autodefrag affects newly written data, it can read a few adjacent blocks (up to 64KiB) and write the contiguous extent to a new location. The adjacent blocks will be unshared. This happens on a smaller scale than the on-demand defrag and doesn’t have the same impact.

RAID1, RAID10

The simple redundancy RAID levels utilize different mirrors in a way that does not achieve the maximum performance. The logic can be improved so the reads will spread over the mirrors evenly or based on device congestion.

RAID56

Please see https://btrfs.readthedocs.io/en/latest/btrfs-man5.html#raid56-status-and-recommended-practices .

Device replace

Device replace and device delete insist on being able to read or reconstruct all data. If any read fails due to an IO error, the delete/replace operation is aborted and the administrator must remove or replace the damaged data before trying again.

On-disk format

The filesystem disk format is stable. This means it is not expected to change unless there are very strong reasons to do so. If there is a format change, filesystems which implement the previous disk format will continue to be mountable and usable by newer kernels.

The core of the on-disk format that comprises building blocks of the filesystem:

layout of the main data structures, e.g. superblock, b-tree nodes, b-tree keys, block headers
the COW mechanism, based on the original design of Ohad Rodeh’s paper “B-trees, Shadowing and Clones” (http://sylab-srv.cs.fiu.edu/lib/exe/fetch.php?media=paperclub:shadow_btree.pdf)

Newly introduced features build on top of the above and could add specific structures. If a backward compatibility is not possible to maintain, a bit in the filesystem superblock denotes that and the level of incompatibility (full, read-only mount possible).