borg-mount(1)

📦
version 2.0.0b25 · 5 versions
, in ubuntu stonking

💖 NAME 💖

borg-mount — mounts an archive or a whole entire repository as a FUSE filesystem. It's from the borg backup tool bestie, and it's giving filesystem-but-make-it-a-backup 💅

🌈 SYNOPSIS 🌈

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

✨ DESCRIPTION ✨

okay so this command mounts a repository or an archive as a FUSE filesystem. use case? browsing and restoring individual files. that's the whole vibe. 🦋

when you're restoring, keep in mind that the current FUSE implementation does not support special fs flags. on Linux, POSIX ACLs of the archived fs objects are exposed (read-only) via the system.posix_acl_access and system.posix_acl_default extended attributes, so tools like getfacl or rsync -A can read them off the mounted archive. but heads up: the mount does not enforce the ACLs for permission checks. on other platforms, ACLs are just not supported at all, sorry. 😭

when you mount a repository, there's one top directory per archive, and the directory structure below those gets loaded on-demand from the repository when you actually enter those directories. so yeah, expect some delay bestie, it's not instant, it's ✨loading✨.

by default those top directories are named like the archives. but since archives of a series all have the same name, -{id:.8} (the first 8 hex digits of the archive id) gets appended whenever a name is not unique. wanna name them differently? set the BORG_MOUNT_ARCHIVE_DIR_FORMAT environment variable to a format string using the placeholders of borg repo-list --format, like {name}-{time:%Y-%m-%dT%H:%M:%S} or {hostname}-{name}. names that are still not unique get -{id:.8} appended. periodt.

Note: ⚠️ Borg stores symbolic links as-is. Consequently, when an archive or repository is mounted, symbolic links may resolve to locations outside of the mountpoint, either because they are absolute or because relative links traverse outside of the mounted tree. Normal UNIX pathname resolution applies: most tools follow symbolic links by default and may therefore access files or directories that are not part of the mounted archive. Consequently, operations intended to inspect archived data may instead access "live" data from the host filesystem. 🫠 On Linux, this can be prevented by remounting the mountpoint with the nosymfollow VFS mount option, for example: borg -r <repo path> mount <mountpoint> mount -o remount,nosymfollow <mountpoint> Alternatively, access the mounted archive from an appropriately isolated environment (for example, a container or chroot).

unless the --foreground option is given, the command runs in the background until the filesystem is unmounted. main character energy: it just vibes there in the back. 🧚

💫 Performance tips

  • When doing a "whole repository" mount: do not enter archive directories if not needed; this avoids 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. it's invoked as borgfs [REPOSITORY] MOUNTPOINT [PATH...], taking the repository as its first positional argument (if it's not given, -r / BORG_REPO is used). this also works in fstab entries:

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

to let a regular user 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 read 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. choose your fighter. 🥊

the uid and gid mount options (implemented by Borg) can override the user and group IDs of all files (i.e., borg mount -o uid=1000,gid=1000).

the man page also references user_id and group_id mount options (implemented by FUSE) which specify the user and group ID of the mount owner (also known as the user who does the mounting). it's set automatically by libfuse (or the filesystem if libfuse is not used). but you should not specify these manually, bestie. 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 scope, different vibe. 💅

👑 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; layout may change in the future. ⚠️
  • allow_damaged_files: by default, damaged files (where chunks are missing or corrupted) will return EIO (I/O error) when trying to read the related parts of the file. set this option to replace the damaged parts with all-zero bytes instead.
  • 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. 🔒

on Windows, borg mount needs WinFsp (https://winfsp.dev/) and mfusepy. MOUNTPOINT must either be an unused drive (like X:) or a not-yet-existing directory (WinFsp creates it when mounting and removes it when unmounting). borg mount always stays in the foreground there and borg umount is not supported: to unmount, stop borg mount using Ctrl+C or Ctrl+Break. all files belong to the user who mounts, unless the uid / gid mount options (which are implemented by WinFsp there, not by Borg) say otherwise. ignore_permissions has no effect. WinFsp does not support hard link counts (they are always 1). 💀

the BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is for advanced users to tweak 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. 🔥

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 delete data unintentionally. so like, let it be. 🫶

when running in the foreground, ^C/SIGINT cleanly unmounts the filesystem, but other signals or crashes do not. iykyk. ✨

🐛 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 bestie. 🎀

🌸 OPTIONS 🌸

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

🎀 arguments 🎀

  • MOUNTPOINT — where to mount the filesystem 📍
  • PATH — paths to extract; patterns are supported 🌟

💅 options 💅

  • -f, --foreground — stay in foreground, do not daemonize
  • -o — extra mount options
  • --numeric-ids — use numeric user and group identifiers from archives

🦋 Archive filters 🦋

  • -a PATTERN, --match-archives PATTERN — only consider archives matching all patterns. see "borg help match-archives".
  • --sort-by KEYS — comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
  • --first N — consider the first N archives after other filters are applied
  • --last N — consider the last N archives after other filters are applied
  • --oldest TIMESPAN — consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
  • --newest TIMESPAN — consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m.
  • --older TIMESPAN — consider archives older than (now - TIMESPAN), e.g., 7d or 12m.
  • --newer TIMESPAN — consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.

💜 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

that's it, that's the page, no cap. this one's from the borg backup tool — dated 2026-10-07, and it's borg-mount(1), your fave. go mount something cute. 🫶✨🎀

📦 where this page comes from