btrfs-check

Check a btrfs filesystem

$ sudo btrfs [[c|check]] [path/to/partition]

$ sudo btrfs [[c|check]] --repair [path/to/partition]

$ sudo btrfs [[c|check]] [[-p|--progress]] [path/to/partition]

$ sudo btrfs [[c|check]] --check-data-csum [path/to/partition]

$ sudo btrfs [[c|check]] [[-s|--super]] [n] [path/to/partition]

$ sudo btrfs [[c|check]] --repair --init-csum-tree [path/to/partition]

$ sudo btrfs [[c|check]] --repair --init-extent-tree [path/to/partition]

btrfs check [options]

-r, --repair
    Attempt to repair the filesystem.
Warning: This option is extremely dangerous and can cause further damage or data loss. Use only if you know what you're doing and have full backups.

-s, --superblock
    Use specific superblock (0, 1, or 2) for checking. Useful if the default superblock is corrupted.

-q, --quiet
    Suppress most output messages, showing only critical errors.

-v, --verbose
    Print more information and details during the check process.

--force
    Force checking even if the filesystem is mounted or appears unhealthy.
Highly discouraged on a mounted filesystem.

-p, --progress
    Show progress of the checking process.

--clear-space-cache v1|v2
    Clear and rebuild the specified version of the space cache. Can help with space accounting issues.

--check-data-csum
    Verify checksums of data extents in addition to metadata. This can be very slow and memory-intensive.

btrfs-check is a crucial utility for Btrfs filesystems, designed to verify the consistency and integrity of the filesystem's metadata. It operates by scanning the filesystem's internal structures, such as block groups, trees (extent tree, chunk tree, root tree), and checksums, to identify any inconsistencies or corruption. By default, btrfs-check performs a read-only examination, reporting errors without attempting any modifications or repairs. This non-destructive behavior is critical for safe initial assessment. For actual repair operations, a separate --repair option exists, which is extremely dangerous and generally advised against unless under expert guidance and with full backups, as it can potentially worsen corruption or lead to data loss. It is strongly recommended to run btrfs-check on an unmounted Btrfs filesystem to ensure accurate results and prevent further damage. Its primary role is to diagnose issues before attempting recovery or repair with more specialized tools.

btrfs-check by default is a read-only tool. It will not repair your filesystem unless explicitly told to, via --repair.
Using the --repair option is highly discouraged without a complete understanding of Btrfs internals and proper backups. It can worsen filesystem corruption or lead to irreversible data loss.
The filesystem should always be unmounted before running btrfs-check. Running it on a mounted filesystem can lead to inaccurate results or further corruption.
Even if btrfs-check reports no errors, it does not guarantee the filesystem is perfectly healthy, as it primarily focuses on metadata integrity and not necessarily all data integrity unless --check-data-csum is used.

The --repair option is a last resort. If btrfs-check reports significant errors, the recommended approach is often to back up what data can be salvaged using btrfs-restore or similar tools, and then recreate the filesystem. Manual repair using --repair often requires deep understanding of Btrfs internal structures.

btrfs-check is an offline tool, requiring the filesystem to be unmounted. For online integrity checks, btrfs scrub is used, which verifies data and metadata checksums while the filesystem is mounted and in use.

btrfs-check is an integral part of the Btrfs filesystem utilities. Btrfs development started around 2007, and btrfs-check has been a core component since early stages, evolving with the filesystem itself. Its design emphasizes safety by defaulting to a read-only mode, a crucial feature given the complexity of filesystem repair. Over time, new options have been added to assist in diagnosing specific corruption scenarios and improving its diagnostic capabilities.

btrfs(8), btrfs-scrub(8), btrfs-restore(8), fsck(8)