btrfs-scrub

Start a scrub

$ sudo btrfs [[sc|scrub]] start [path/to/btrfs_mount]

$ sudo btrfs [[sc|scrub]] status [path/to/btrfs_mount]

$ sudo btrfs [[sc|scrub]] [[c|cancel]] [path/to/btrfs_mount]

$ sudo btrfs [[sc|scrub]] [[r|resume]] [path/to/btrfs_mount]

$ sudo btrfs [[sc|scrub]] start -B [path/to/btrfs_mount]

$ sudo btrfs [[sc|scrub]] start [[-q|--quiet]] [path/to/btrfs_mount]

btrfs scrub start|stop|status|cancel|pause|resume|detach [options]

-B, --background
    Run scrub in background; exit immediately after spawning workers (start)

-b size, --block-size size
    IO block size for reading data (default: 128KiB) (start)

-c size
    Block size for checksum verification (default: 128KiB) (start)

-d, --dirty
    Mark scrub state as dirty initially; also scrubs free space (start)

-f, --force
    Force scrub on read-only mounted filesystem (start)

-n, --no-repair
    Read-only scrub; detect but do not repair errors (start)

-q, --quiet
    Suppress progress output (start, status)

-r
    Deprecated; use -n instead for read-only scrubbing (start)

-S path
    Path to store scrub repair bitmap (start)

-v
    Verbose output (start, status)

-x
    Skip mirrored user-reference blocks (start)

-d
    Show detailed statistics (status only)

The btrfs scrub command is a key maintenance tool for BTRFS filesystems, designed to detect and repair data corruption. It systematically reads all data and metadata blocks on a mounted filesystem, verifies checksums, and uses redundancy (like RAID1, RAID5/6) to repair errors such as bit rot or silent corruption.

Unlike traditional fsck, which requires an unmounted filesystem, scrub operates online, minimizing downtime. It supports background operation, allowing concurrent file access. On single-device setups, it identifies issues but relies on backups for recovery; redundant arrays enable automatic fixes.

Subcommands manage the process: start initiates scrubbing, status monitors progress and statistics (blocks read, errors found/fixed), stop/cancel halts it, pause/resume control ongoing jobs, and detach removes repair logs for devices.

Regular scrubbing (monthly for large/critical FS) ensures integrity. It consumes CPU, memory, and IO, so schedule wisely. Logs errors to kernel ringbuffer and dmesg; use btrfs scrub status for summaries.

Highly IO/CPU intensive on large filesystems; can take days. Requires mounted FS with write access for repairs (use -f for RO). Insufficient free space may block repairs. Monitor with status; check dmesg for errors. Not suitable for offline checks (use btrfs check).

Reports total/correctable/uncorrectable errors, blocks processed, and speed. Example: 'scrub done on , 0 errors'. Use -d for per-device details.

Repairs use copy/parity data; logs to syslog/dmesg. Unfixable errors marked; run multiple times or restore from backup.

Introduced in BTRFS kernel 2.6.37 (2010) for basic scrubbing. Enhanced in 3.9+ with background mode, repair stats, and RAID5/6 support. Kernel 4.x added free-space scrubbing (-d) and performance optimizations. Remains actively developed for better error handling.

btrfs(8), btrfs-check(8), btrfs-balance(8), mkfs.btrfs(8)