borg-mount(1)

💖 borg-mount(1) 💖

okay bestie, welcome to the borg backup tool corner of the manual, this one is borg-mount(1) and it's genuinely one of the coolest things in the box, no cap. let's get into it 🦋

---

✨ Name ✨

borg-mount — mount an archive, or a whole entire repository, as a FUSE filesystem. yes. like, actually mount it. like it's a real directory. iconic behavior honestly 💅

---

🌸 Synopsis 🌸

borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT
[PATH...]

---

🎀 Description 🎀

so this command mounts a repository or an archive as a FUSE filesystem, and it's lowkey perfect for browsing around or pulling out individual files when you don't wanna do a whole extract situation. obsessed.

When you're restoring stuff, pls keep in mind that the current FUSE implementation does not support special filesystem flags and ACLs. it's just not giving that rn 😭

When you mount a repository (not an archive), the top-level directories get named after the archives, and the directory structure underneath them is loaded on-demand from the repository whenever you actually enter those directories. so yeah, expect a lil delay. it's not broken, it's just thinking 🧚

Note (this one's important, bestie, fr fr): Borg stores symbolic links as-is. So when an archive or repository is mounted, symbolic links may resolve to locations outside of the mountpoint — either because they're absolute, or because relative links traverse outside of the mounted tree. Normal UNIX pathname resolution applies here: most tools follow symbolic links by default and may therefore access files or directories that are not part of the mounted archive. Which means operations you intended to inspect archived data with may instead be accessing "live" data from the host filesystem. 💀 On Linux, you can prevent this by remounting the mountpoint with the nosymfollow VFS mount option, like so: borg mount <repo path> <mountpoint> mount -o remount,nosymfollow <repo path> <mountpoint> Alternatively, access the mounted archive from an appropriately isolated environment — for example, a container or a chroot. 🫶

Unless you pass the --foreground option, the command will run in the background until the filesystem gets unmounted. main character energy: it just goes off and does its thing 🌈

Performance tips (because we love an efficient queen 👑):

• when doing a "whole repository" mount: do not enter archive directories if you don't need to; this avoids that on-demand loading.
• only mount a specific archive, not the whole repository.
• only mount specific paths in a specific archive, not the complete archive.

The command borgfs provides a wrapper for borg mount. This can also be used in fstab entries:

/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0

To allow a regular user to use fstab entries, add the user option:

/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0

For FUSE configuration and mount options, go peek at the mount.fuse(8) manual page. ✨

Borg's default behavior is to use the archived user and group names of each file and map them to the system's respective user and group ids. Alternatively, using numeric-ids will instead use the archived user and group ids without any mapping at all. pick your fighter 🥊

The uid and gid mount options (implemented by Borg) can be used to override the user and group ids of all files — i.e., borg mount -o uid=1000,gid=1000.

The man page references the user_id and group_id mount options (implemented by FUSE), which specify the user and group id of the mount owner (aka, the user who does the mounting). It's set automatically by libfuse (or the filesystem, if libfuse isn't used). However — and listen closely bestie — you should not specify these manually. Unlike the uid and gid mount options which affect all files, user_id and group_id affect the user and group id of the mounted (base) directory. different thing, don't mix them up 🙈

Additional mount options supported by borg:

• versions: when used with a repository mount, this gives a merged, versioned view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
• allow_damaged_files: by default, damaged files (where missing chunks were replaced with runs of zeros by borg check --repair) are not readable and return EIO (I/O error). Set this option to read such files.
• ignore_permissions: for security reasons the default_permissions mount option is internally enforced by borg. ignore_permissions can be given to not enforce default_permissions.

The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users to tweak the performance. It sets the number of cached data chunks; additional memory usage can be up to ~8 MiB times this number. The default is the number of CPU cores. number of cores, bestie, that's the vibe 🌟

When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process to unintentionally delete data. so, yeah, that's very much a "do not do this" situation 😭

When running in the foreground, Ctrl+C/SIGINT cleanly unmounts the filesystem, but other signals or crashes do not. noted. periodt.

Debugging:

borg mount usually daemonizes, and the daemon process sends stdout/stderr to /dev/null. So you need to either use -f / --foreground to make it stay in the foreground and not daemonize, or use BORG_LOGGING_CONF to reconfigure the logger to output to a file. that's the whole trick, iykyk 💅

---

✨ OPTIONS ✨

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

🦋 arguments 🦋

• REPOSITORY_OR_ARCHIVE — the repository or archive you wanna mount.
• MOUNTPOINT — where to mount the filesystem.
• PATH — paths to extract; patterns are supported ✨

💜 options 💜

• --consider-checkpoints — show checkpoint archives in the repository contents list (default: hidden).
• -f, --foreground — stay in foreground, do not daemonize.
• -o — extra mount options.
• --numeric-owner — deprecated, use --numeric-ids instead. (we do not stan her anymore 🙈)
• --numeric-ids — use numeric user and group identifiers from archive(s).

🌸 Archive filters 🌸

• -P PREFIX, --prefix PREFIX — only consider archive names starting with this prefix. (deprecated)
• -a GLOB, --glob-archives GLOB — only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see borg help patterns.
• --sort-by KEYS — comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp.
• --first N — consider first N archives after other filters were applied.
• --last N — consider last N archives after other filters were applied.

🎀 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. ✂️

---

🌈 SEE ALSO 🌈

borg-common(1), borg-umount(1), borg-extract(1)

---

👑 Author 👑

The Borg Collective

---

okay that's the whole page bestie, you're fully equipped now, go mount something 🫶✨

this was page 2026-07-18 of borg-mount(1) — mwah, love u, bye 💖