BTRFS-IMAGE(8)

📦
version 7.3 · 20 versions
, in arch rolling

💖 BTRFS-IMAGE — the manual, bestie edition 💖

okay so this is btrfs-image from section 8 of the manual (the sysadmin one, iykyk), and it is literally the tool you call when you need to create or restore an image of a btrfs filesystem. yes. that one. sit down, we're doing this together 🫶

✨ NAME ✨

btrfs-image — create/restore an image of the filesystem

🌸 SYNOPSIS 🌸

btrfs-image [options] <source> <target>

🦋 DESCRIPTION 🦋

so btrfs-image makes an image of a btrfs filesystem. all data gets zeroed, but metadata and the like? preserved, iconic, untouched. it's mainly a debugging tool — like, this is the "bestie send me your filesystem so I can look at it" move 💅

in dump mode, source is the btrfs device/file and target is the output file (and yes, you can use - for stdout, we love a pipe moment ✨).

in restore mode (that's the -r option), source is the dumped image and target is the btrfs device/file. flip it and reverse it 🎀

👑 OPTIONS 👑

  • -r — Restore a metadump image. by default this fixes super's chunk tree by using 1 stripe pointing to primary device, so that the filesystem can be restored by running tree log reply if that's possible. want to restore without changing the number of stripes in the chunk tree? check the -o option, bestie.
  • -c <value> — Compression level (0 ~ 9).
  • -t <value> — Number of threads (1 ~ 32) to be used to process the image dump or restore. go off, multithreading 💀
  • -o — Use the old restore method. heads up: this does not fixup the chunk tree, so the restored file system will not be able to be mounted. yeah. that's the tradeoff. 🚨
  • -s — Sanitize the file names when generating the image. Not recommended — it would introduce new file name hash mismatches, so if your problem involves subvolume tress, it can even mask existing problems. furthermore, kernels can not do proper path resolution due to the introduced hash mismatches. one -s means just generate random garbage, which means the directory hash won't match its file names. using two -s will calculate a collision for the file name so that the hashes match, and if it can't calculate a collision then it will just generate garbage. the collision calculator is very time and CPU intensive. like, she's working hard, respect her 😭
  • -w — Walk all the trees manually and copy any blocks that are referenced. use this option if your extent tree is corrupted, to make sure that all of the metadata is captured. corrupted extent tree? this is your girl 🫶
  • -m — Restore for multiple devices. more than 1 device should be provided, no cap.
  • --version — Print the btrfs-image version, builtin features and exit. simple. clean. periodt ✨

💀 EXIT STATUS 💀

btrfs-image will return 0 if no error happened. if any problems happened, 1 will be returned. that's it, that's the vibe check.

🌈 SEE ALSO 🌈

mkfs.btrfs(8) <>

okay that's the whole page, you ate that 💅 and just so you know where all this lore came from: this is version 7.3, dated Oct 24, 2026. mwah, go image something 🔥👑

📦 where this page comes from