btrfs-restore

Restore files from a damaged Btrfs filesystem

TLDR

Restore all files from a btrfs filesystem to a given directory

$ sudo btrfs [[rest|restore]] [path/to/btrfs_device] [path/to/target_directory]

List (don't write) files to be restored from a btrfs filesystem

$ sudo btrfs [[rest|restore]] [[-D|--dry-run]] [path/to/btrfs_device] [path/to/target_directory]

Restore files matching a given regex ([c]ase-insensitive) files to be restored from a btrfs filesystem (all parent directories of target file(s) must match as well)

$ sudo btrfs [[rest|restore]] --path-regex [regex] -c [path/to/btrfs_device] [path/to/target_directory]

Restore files from a btrfs filesystem using a specific root [t]ree bytenr (see btrfs-find-root)

$ sudo btrfs [[rest|restore]] -t [bytenr] [path/to/btrfs_device] [path/to/target_directory]

Restore files from a btrfs filesystem (along with metadata, extended attributes, and Symlinks), overwriting files in the target

SYNOPSIS

btrfs restore [options...] device [path]

-D, --dry-run
    perform a dry run without writing to the filesystem

-s start
    use superblock copy at byte address start

-t tree
    search for tree roots with objectid tree

-d
    use device scan mode to find all devices

-i
    ignore errors and continue on non-fatal issues

-v
    enable verbose output

-q
    quiet mode, suppress non-error output

-I
    use libuuid to detect filesystem UUID

DESCRIPTION

The btrfs restore command is a specialized utility for recovering metadata from damaged BTRFS filesystems. BTRFS stores multiple copies of critical metadata structures, including superblocks and tree roots, across the device. When a filesystem becomes corrupted—due to power failures, hardware issues, or software bugs—this tool scans the device for valid superblock copies and tree roots, then attempts to reconstruct the filesystem's metadata.

It identifies usable tree roots using checksums and generation numbers, prioritizing the most recent valid ones. The tool can restore the primary superblock and key tree roots like the chunk tree, root tree, and extent tree. Optionally, it writes recovered metadata to a specified output path instead of directly to the device.

Ideal for scenarios where btrfs check --repair fails or the superblock is unreadable. However, it focuses solely on metadata recovery; file data extents may still require further repair. Use in read-only mode first with --dry-run to assess damage without risk.

CAVEATS

Always unmount the filesystem before use. Does not repair data extents or guarantee full recovery. Test with --dry-run first. Multiple devices require -d. Not for mounted filesystems.

USAGE EXAMPLE

btrfs restore -t 5 -i -D /dev/sda1
Scans for root tree (objectid 5), ignores minor errors, dry-run on /dev/sda1.

OUTPUT PATH

Specify path to dump restored metadata files instead of writing to device, e.g., btrfs restore /dev/sda1 ./restore/.

HISTORY

Developed as part of the BTRFS-tools package, introduced with early BTRFS support in Linux kernel 2.6.29 (2009). Enhanced over time for better multi-device handling and root detection, maintained by the BTRFS project under Oracle and community contributors.