borg-extract(1)

💖 borg-extract(1) — the "get ur stuff back" command 💖

okay bestie, welcome to borg-extract from the borg backup tool ✨ this is the one where you pull an archive's contents back out. let's go 🫶

---

🌸 NAME 🌸

borg-extract — Extracts archive contents. literally that's it, that's the job 💅

---

✨ SYNOPSIS ✨

borg [common options] extract [options] NAME [PATH...]

---

🦋 DESCRIPTION 🦋

This command extracts the contents of an archive. yes queen, we're getting ur files back 💖

By default, the entire archive is extracted, but a subset of files and directories can be selected by passing a list of PATH arguments. The default interpretation for the paths to extract is pp: which is a literal path-prefix match. If you want to use e.g. a wildcard, you must select a different pattern style such as sh: or fm:. See borg_patterns for more information. iykyk 🐚

The file selection can be further restricted by using the --exclude option. For more help on include/exclude patterns, see the borg_patterns command output.

By using --dry-run, you can do all extraction steps except actually writing the output data: reading metadata and data chunks from the repository, checking the hash/HMAC, decrypting, and decompressing. it's giving "rehearsal but make it forensic" 💀

--progress can be slower than no progress display, since it makes one additional pass over the archive metadata. (yes bestie, the little bar costs u a whole extra pass, that's the tradeoff 🙈)

Extracting into a non-empty directory replaces existing files that are in the way and leaves all other existing files as they are. The result is a mix of the files that were there before and the extracted files, which might not be what you want — especially not by accident in a directory that is in use (e.g. your home directory). Thus, borg refuses to extract into a non-empty directory unless --continue is given (--dry-run and --stdout do not write into the directory, so they always work). The usual way to restore is to extract into a new, empty directory: after that, the directory has exactly the contents of the extracted archive (or of the selected part of it). 🎀

--continue extracts into a non-empty directory. It is made for continuing a previously interrupted extraction of the same archive into the same directory: an existing regular file that has the same type, permissions (mode), size and modification time as the archived file is considered to be fully extracted already and is skipped. Everything else is extracted, replacing existing files. Files that are in the directory, but not in the archive, are left as they are. --continue is thus also needed to restore files into an existing directory tree. Note that a file that was damaged without a change of its size and modification time (e.g. by bit rot) is skipped, not replaced: remove it before extracting it. 👑

⚠️ bestie that last one is a trap — bit rot keeps the size and mtime, so borg thinks it's already done. delete the file first, fr fr.

If a file's content chunks are missing from the repository or are corrupted (they fail authentication, decryption or decompression), the extraction does not abort: each such chunk is written as all-zero data of the correct size, an error naming the chunk is logged, the file is reported with a warning and the exit code is a warning. The extracted file thus has the correct size and metadata, but wrong (all-zero) content where the damaged chunks were. Run borg check to find out which chunks and archives are affected. This also applies to --dry-run (which thus can be used to find unreadable files) and --stdout. 💀

When using --stats, borg reports the store statistics (lines prefixed with "Store") for the extraction: per-operation call counts and timings, the load/store data volumes and throughput, and cache hits/misses. This includes --dry-run extractions. 📊

Note: Currently, extract always writes into the current working directory ("."), so make sure you cd to the right place before calling borg extract. 🧭 When parent directories are not extracted (because of using file/directory selection or any other reason), Borg cannot restore parent directories' metadata, e.g., owner, group, permissions, etc.

Note: Restoring some file metadata requires root privileges (or equivalent capabilities). This includes the owner and group of files, device nodes, privileged file flags (like immutable or append-only) and privileged extended attributes (like Linux capabilities or trusted.* xattrs). When running as a normal user, borg still extracts the file contents, but the extracted files are owned by the invoking user (the failure to restore ownership is silently ignored: no warning, exit code unaffected), privileged flags are skipped while the other flags are still set, and privileged xattrs and device nodes are skipped with a warning. --numeric-ids does not change this, it only selects whether the archived numeric IDs or the archived user/group names are used. To restore all metadata, run borg extract as root. 👑

---

🌈 OPTIONS 🌈

See borg-common(1) for common options of Borg commands.

🍓 arguments

• NAME — specify the archive name
• PATH — paths to extract; patterns are supported

💅 options

• --list — output a verbose list of items (files, dirs, ...)
• -s, --stats — print store statistics for the extraction
• -n, --dry-run — do not actually change any files
• --numeric-ids — only use numeric user and group identifiers
• --noflags — do not extract/set flags (e.g. NODUMP, IMMUTABLE)
• --noacls — do not extract/set ACLs
• --noxattrs — do not extract/set xattrs
• --stdout — write all extracted data to stdout
• --sparse — create holes in the output sparse file from all-zero chunks
• --continue — extract into a non-empty directory, e.g. to continue a previously interrupted extraction of the same archive: skip files that are fully extracted already, replace other existing files

🧚 Include/Exclude options

• -e PATTERN, --exclude PATTERN — exclude paths matching PATTERN
• --exclude-from EXCLUDEFILE — read exclude patterns from EXCLUDEFILE, one per line
• --pattern PATTERN — include/exclude paths matching PATTERN
• --patterns-from PATTERNFILE — read include/exclude patterns from PATTERNFILE, one per line
• --strip-components NUMBER — Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

---

🔥 EXAMPLES 🔥

# Extract entire archive (into the current directory, which must be empty)
$ borg extract my-files

# Continue an interrupted extraction (or extract into a non-empty directory)
$ borg extract --continue my-files

# Extract entire archive and list files while processing
$ borg extract --list my-files

# Verify whether an archive could be successfully extracted, but do not write files to disk
$ borg extract --dry-run my-files

# Extract the "src" directory
$ borg extract my-files home/USERNAME/src

# Extract the "src" directory but exclude object files
$ borg extract my-files home/USERNAME/src --exclude '*.o'

# Extract only the C files
$ borg extract my-files 'sh:home/USERNAME/src/*.c'

# Restore a raw device (must not be active/in use/mounted at that time)
$ borg extract --stdout my-sdx | dd of=/dev/sdx bs=10M

---

👑 SEE ALSO 👑

borg-common(1), borg-mount(1)

---

🫶 Author 🫶

The Borg Collective

---

and that's the whole page bestie, u ate 💅 this was the borg backup tool manpage, dated 2026-10-07 — go forth and extract responsibly, no cap 🌟💖✨