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] <device>

-p, --progress
    Display scan progress

-s, --readonly
    Read-only mode (default)

--repair
    Attempt repairs (DANGER: high risk of data loss)

--init-extent-tree
    Reinitialize extent allocation tree (DANGER)

--init-csum-tree
    Reinitialize checksum tree (DANGER)

--clear-free-space-tree
    Clear free space tree (DANGER)

--tree-root <bytenr>
    Specify tree root bytenr (DANGER)

--checkpoint-root <bytenr>
    Specify checkpoint root bytenr (DANGER)

--subvol-root <bytenr>
    Specify subvolume root bytenr (DANGER)

-Q, --qgroup-report
    Report quota group existence

--qgroup-report-all
    Full quota group report

--qgroup-rescan
    Rescan quota groups (DANGER)

--check-data-csum
    Verify data block checksums

--check-integrity
    Print filesystem integrity stats

--convert-extent-tree
    Convert extent tree to v2 (experimental, DANGER)

The btrfs check command is a critical utility from the btrfs-progs package used to verify the structural integrity of BTRFS filesystems. It scans metadata trees, extent allocations, checksums, and optionally data blocks on a specified device. By default, it performs a read-only check, reporting errors without modifications. This makes it essential for diagnosing corruption issues that might arise from power failures, hardware faults, or software bugs.

Key features include progress reporting, qgroup verification, and integrity statistics. For repairs, the --repair option attempts to fix detected problems, but this is extremely risky and can render the filesystem unmountable or cause data loss. Specialized modes like --init-extent-tree or --init-csum-tree rebuild specific trees, reserved for experts after backups.

Always run on unmounted filesystems. It's invoked as fsck.btrfs by tools like fsck. Regular use helps maintain reliability, but misuse demands full backups first. Supports advanced diagnostics like data checksum verification, vital for ensuring no silent corruption.

Never run on mounted filesystems. --repair and similar options can destroy data; backups mandatory. Not a substitute for regular btrfs scrub. May require superuser privileges.

btrfs check /dev/sdb1
Basic read-only integrity check.

btrfs check --repair /dev/sdb1
Repair mode (backup first!).

btrfs check --check-data-csum /dev/sdb1
Verify data checksums.

For mounted filesystems, use btrfs scrub instead for safer checks.

Developed alongside BTRFS filesystem (introduced 2009 by Chris Mason at Oracle). btrfs-progs tools like btrfs check evolved from early prototypes, with major enhancements in kernel 3.x/4.x eras for repair capabilities and qgroup support around 2014.

btrfs(8), mkfs.btrfs(8), btrfs-scrub(8), fsck(8)