Skip to content

Instantly share code, notes, and snippets.

@1oh1

1oh1/borgbackup_usage_macos.md

Created January 3, 2026 19:05
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save 1oh1/3e6149bf04dbe18d65713887d5e1b58b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save 1oh1/3e6149bf04dbe18d65713887d5e1b58b to your computer and use it in GitHub Desktop.
Download ZIP
BorgBackup Usage on MacOS
Raw
borgbackup_usage_macos.md

Installation

  1. Install borgbackup (no fuse support by default on MacOS, can't mount archives). Useful if you only want to back up and don't want to mount anything or intend to mount on another system
brew install borgbackup
  1. Install patched version of borgbackup with fuse support for mounting backups
brew remove borgbackup
brew install --cask macfuse
brew install borgbackup/tap/borgbackup-fuse
  1. (OPTIONAL - for borgbackup-fuse) Go to Settings > General > Login Items & Extensions > App Background Activity Ensure "Benjamin Fleischer" is in the list and ticked. If not, try mounting a backup and when the popup shows that says an extension was blocked, go the settings page and enable it. You will need to restart the Mac after it's enabled.

See also:

Backing up

  1. Create a (password encrypted) repository
borg init --encryption=repokey /Volumes/ExternalSSD-2TB/backups/mac-backup
  1. Create a (no password) repository
borg init --encryption=none /Volumes/ExternalSSD-2TB/backups/mac-backup
  1. Do a dry-run before actually creating an archive
borg create --dry-run --list --stats --progress --compression lz4 /Volumes/ExternalSSD-2TB/backups/mac-backup::downloads $HOME/Downloads
  1. Add a named archive (e.g. home-dir_17-nov) to the repository and back up files while excluding unwanted dirs
borg create --list --stats --progress --compression lz4 /Volumes/ExternalSSD-2TB/backups/mac-backup::downloads-dir $HOME/Downloads

borg create --list --stats --progress --compression lz4 /Volumes/ExternalSSD-2TB/backups/mac-backup::desktop-dir $HOME/Desktop

borg create --list --stats --progress --compression lz4 --exclude .tools --exclude .npm --exclude .gem --exclude pkg-cache --exclude tmp-workspace /Volumes/ExternalSSD-2TB/backups/mac-backup::home-dir $HOME/

borg create --list --stats --progress --compression lz4 --exclude '/Users/1oh1/.tools' --exclude '/Users/1oh1/Library/Group Containers/Office/' --exclude .npm --exclude .gem --exclude pkg-cache --exclude '/Users/1oh1/tmp-workspace/'  --exclude tmp-workspace /Volumes/ExternalSSD-2TB/backups/mac-backup::home-dir_17-nov $HOME/

See also:

Inspecting repositories

  1. List all named archives in a repository
borg list /Volumes/ExternalSSD-2TB/backups/mac-backup
  1. List overall repository information like original size, compressed size, de-duped size, encryption info, etc
borg info /Volumes/ExternalSSD-2TB/backups/mac-backup
  1. List information for a particular archive
borg info /Volumes/ExternalSSD-2TB/backups/mac-backup::home-dir

NOTE: Everything inside /Volumes/ExternalSSD-2TB/backups/mac-backup is part of the repository. DO NOT EDIT the contents of this directory. Do not add/remove stuff like .DS_Store, etc.

See also:

Extracting from archives

  1. Extract all files from archive (to current directory only, no support for other dirs) and list files while processing
mkdir ~/dir_to_extract_to
cd ~/dir_to_extract_to
borg extract --list /Volumes/ExternalSSD-2TB/backups/mac-backup::desktop-dir
  1. Extract a file or directory from the archive
mkdir ~/dir_to_extract_to
cd ~/dir_to_extract_to
borg extract --list /Volumes/ExternalSSD-2TB/backups/mac-backup::home-dir "Users/1oh1/.zsh_history"

See also:

Mounting archives

  1. Create a directory for the mount point
mkdir ~/borg_mnt
  1. Mount an archive from a repository (use password from pass command - assuming pass is installed and password is already stored in 'borg_mac')
export BORG_PASSCOMMAND='pass show borg_mac'
borg mount -o uid=$UID,gid=$GID /Volumes/ExternalSSD-2TB/backups/mac-backup::desktop-dir ~/borg_mnt
  1. Mount an archive from repository while prompting for password
borg mount -o uid=$UID,gid=$GID /Volumes/ExternalSSD-2TB/backups/mac-backup::desktop-dir ~/borg_mnt
  1. Unmount archive
borg umount ~/borg_mnt

See also:

NOTE: Install qlmarkdown to view this file in Markdown format

brew install --cask qlmarkdown
xattr -r -d com.apple.quarantine /Applications/QLMarkdown.app

Use borg without entering the password

  1. Install pass, gpg and pinentry-mac
brew install pass gpg pinentry-mac
  1. Create or import GPG keys (fetch keys from password manager under 'GPG' folder)
gpg --full-generate-key

OR

gpg --import combined_keys.asc
  1. Trust imported GPG key (if importing keys)
gpg --edit-key 7361CE8740A6F719A2524D93CE06205466820CEC
gpg> trust
Your decision? 5
gpg> quit
gpg --import-ownertrust ownertrust.txt
  1. Create or edit ~/.gnupg/gpg-agent.conf
pinentry-program /opt/homebrew/bin/pinentry-mac
default-cache-ttl 86400
max-cache-ttl 86400
  1. List GPG keys and pick your key
gpg --list-keys --keyid-format=long
/Users/1oh1/.gnupg/pubring.kbx
------------------------------
pub   ed25519/CE06205466820CEC 2026-01-03 [SC]
      7361CE8740A6F719A2524D93CE06205466820CEC
uid                 [ultimate] 1oh1 (Used for 'pass' password manager on MacOS) <[email protected]>
sub   cv25519/5016A9C7029C46FB 2026-01-03 [E]
  1. Initialize pass with your GPG key
pass init "$(gpg --with-colons --list-keys 7361CE8740A6F719A2524D93CE06205466820CEC | awk -F: '$1=="uid" {print $10; exit}')"
  1. Create and store passwords in pass
pass insert apps/borg/mac/backup
/Users/1oh1/.password-store/apps
/Users/1oh1/.password-store/apps/borg
/Users/1oh1/.password-store/apps/borg/mac
Enter password for apps/borg/mac/backup:
Retype password for apps/borg/mac/backup:
  1. List passwords in pass and verify that you can fetch the password you need
pass
Password Store
├── apps
│   └── borg
│     └── mac
│         └── backup
├── borg_mac
└── pw-is-test

pass show apps/borg/mac/backup
<REDACTED>
  1. Before running any borg command, set the password that it should use with
export BORG_PASSCOMMAND='pass show <borg-password>'

Example:
export BORG_PASSCOMMAND='pass show apps/borg/mac/backup'
  1. Run a borg command that uses the password
borg info /Volumes/ExternalSSD-2TB/backups/mac-backup
Repository ID: d54a97bad3e5f7e344e2626fcded5f0fbc33f08b1b7f152c4ef985a6e2ed57a0
Location: /Volumes/ExternalSSD-2TB/backups/mac-backup
Encrypted: Yes (repokey)
Cache: /Users/1oh1/.cache/borg/d54a97bad3e5f7e344e2626fcded5f0fbc33f08b1b7f152c4ef985a6e2ed57a0
Security dir: /Users/1oh1/.config/borg/security/d54a97bad3e5f7e344e2626fcded5f0fbc33f08b1b7f152c4ef985a6e2ed57a0
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
All archives:              771.59 GB            315.53 GB            121.02 GB

                       Unique chunks         Total chunks
Chunk index:                  982732              3811494

NOTE: Make sure your GPG keys are exported and backed up in a safe location. Also make sure you have a backup of your passwords (everything under /Users/$USER/.password-store)

Links:

  1. https://borgbackup.readthedocs.io/en/stable/installation.html
  2. https://borgbackup.readthedocs.io/en/stable/usage/mount.html
  3. https://share.google/aimode/myTOWfihUsW15gdOC
  4. https://docs.borgbase.com/restore/borg/mount
  5. borgbackup/borg#5522
  6. https://dev.to/zemse/setup-gpg-on-macos-2iib
  7. https://serverfault.com/a/1040984/218766
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment