BTRFS-RESTORE(8)

📦
version 7.3 · 20 versions
, in arch rolling

💖 NAME 💖

btrfs-restore — bestie's emergency rescue mission: try to restore files from a damaged filesystem image 🫶

✨ SYNOPSIS ✨

btrfs restore [options] <device> <path> | -l <device>

🌸 DESCRIPTION 🌸

okay so btrfs restore is literally the "my filesystem is fighting for its life" tool. It tries to salvage files out of a damaged filesystem and drop them into path — or it can just list the subvolume tree roots for you instead. And the most important thing: the filesystem image is not modified. Not one bit. Read-only queen behavior 💅

Here's the vibe check: if your filesystem is damaged and the other tools can't fix it — and by "other tools" I mean btrfs-check(8) and btrfs-rescue(8) — then btrfs restore is who you call. It'll go retrieve file data as far as the metadata is readable. The checks it runs are way less strict, which lowkey means it usually gets far enough to pull data from the whole filesystem. Slay? Kinda. But there's a catch, and it's a real one: some data might be incomplete, or might be from older versions if those happen to be available. So no cap — you might get your file, you might get an older version of your file. Still eating though 😭

There's a whole menu of options for restoring different kinds of file metadata. Bestie strategy: do a dry run first to see how the process goes, then layer on more options to widen the set of restored metadata. Vibe check before the rescue mission, yk?

And if you're dealing with images that have damaged tree structures, there are several options to point the process at some spare copy. Safe backups come in clutch 🦋

🎀 OPTIONS 🎀

  • -s, --snapshots — get the snapshots too! they're skipped by default, so you have to ask nicely ✨
  • -x, --xattr — grab the extended attributes as well 💜
  • -m, --metadata — restore owner, mode and times for files and directories. the whole little identity of the file, restored 🫶
  • -S, --symlinks — restore symbolic links, not just normal files 🎀
  • -i, --ignore-errors — ignore errors during restoration and just keep going. she's unbothered. she's continuing 💅
  • -o, --overwrite — overwrite directories/files in path, e.g. for repeated runs. so you can run it again and again without the old stuff in the way 🔥
  • -t <bytenr> — use bytenr to read the root tree ⭐
  • -f <bytenr> — only restore files that are under the specified subvolume root, the one pointed to by bytenr
  • -u, --super <mirror> — use the given superblock mirror, identified by <mirror>. it can be 0, 1 or 2 (those are the only options, don't get creative 🙈)
  • -r, --root <rootid> — only restore files that are under a specified subvolume whose objectid is rootid
  • -d — find directory
  • -l, --list-roots — list subvolume tree roots! and plot twist, this output can be used as an argument for -r 👑
  • -D, --dry-run — dry run: only list the files that would be recovered. no actual restoring, just a little preview ✨
  • --path-regex <regex> — restore only filenames matching a regular expression (that's regex(7), linked over at <https://man7.org/linux/man-pages/man7/regex.7.html>) with a mandatory format:
^/(|home(|/username(|/Desktop(|/.*))))$

fr fr, the format is not very comfortable, and it restores all files in the directories in the whole path. so this is not useful for restoring a single file in a deep hierarchy. it's giving "well, sort of" 🫠

  • -c — ignore case (--path-regex only)
  • -v, --verbose — (deprecated) alias for the global -v option. she's old, she's legacy, be gentle 🥲

🌈 Global options 🌈

  • -v, --verbose — be verbose and print what is being restored. yes bestie, tell me everything 💬

💀 EXIT STATUS 💀

btrfs restore returns a zero exit status if it succeeds. Non zero gets returned in case of failure. Zero = we ate. Non-zero = we did not eat 😭

🧚 AVAILABILITY 🧚

btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>. go read the docs, they're right there, they're free 💜

🦋 SEE ALSO 🦋

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

okay that's the whole page, you're officially trained 🎓 this was version 7.3 from Oct 24, 2026 — take care of your filesystems and back them up, i'm literally begging you 🙏💖

📦 where this page comes from