This page looks best with JavaScript enabled

Backing up data with Borg

 ·  ☕ 4 min read

borg is a deduplicating backup program. Optionally, it supports compression and authenticated encryption.
The main goal of Borg is to provide an efficient and secure way to backup data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. The authenticated encryption technique makes it suitable for backups to not fully trusted targets.
Source code available at GitHub.

Create a backup

  • Initialize a new NOT encrypted backup repository:

    borg init -e none /path/to/repo
  • Initialize a new encrypted (with password) backup repository:

    borg init -e keyfile /path/to/repo

    Note: encrypted keys stored in ~/.config/borg/keys/

  • Initialize a new encrypted (with key file) backup repository:

    borg init -e repokey /path/to/repo
  • Create a backup archive with your documents:

    borg create /path/to/repo::docs_4nov20 ~/Dokumente
  • Create a backup archive with your documents, but excluding “scans” subfolder:

    borg create /path/to/repo::docs_4nov20 ~/Dokumente --exclude ~/Dokumente/scans
  • Create a compressed (with zstd) backup archive with your documents, show progress and statistic:

    borg create --stats --progress --compression zstd /path/to/repo::docs_4nov20 ~/Dokumente

    Following compression methods available: none, lz4, zstd, zlib, lzma, auto.

Restore a backup

There are two ways to restore files from a borg backup repository:

  1. borg mount - use this if:
    • you don’t precisely know what files you want to restore
    • you don’t know which archive contains the files (in the state) you want
    • you need to look into files / directories before deciding what you want
    • you need a relatively low volume of data restored
    • you don’t care for restoring stuff that the FUSE mount is not implementing yet (like special fs flags, ACLs)
    • you have a client with good resources (RAM, CPU, temp. disk space)
    • you want to rather use some filemanager to restore (copy) files than borg extract shell commands
  2. borg extract - use this if:
    • you precisely know what you want (repo, archive, path)
    • you need a high volume of files restored (best speed)
    • you want a as-complete-as-it-gets reproduction of file metadata (like special fs flags, ACLs)
    • you have a client with low resources (RAM, CPU, temp. disk space)

Mount an archive

  • Mount an archive:

    borg mount /path/to/repo::docs_4nov20 /path/to/mountpoint
  • Mount remote archive:

    borg mount ssh://[email protected]:2222/path/to/repo::docs_4nov20 /path/to/mountpoint
  • Unmount archive:

    borg umount /path/to/mountpoint

Extract an archive

  • Extract an archive:
    borg extract /path/to/repo::docs_4nov20 path/to/extract
  • Extract remote archive:
    borg extract ssh://[email protected]:2222/path/to/repo::docs_4nov20

Repository maintenance

  • List archives in repository:

    borg list /path/to/repo
  • Display information about the specified repository:

    borg info /path/to/repo
  • Display information about the specified archive (backup):

    borg info /path/to/repo::docs_4nov20
  • Rename archive in repository:

    borg rename /path/to/repo::archivename newname
  • Delete archive from repository:

    borg delete /path/to/repo::docs_4nov20
  • Find differences (file contents, user/group/mode) between archives:

    borg diff testrepo::archive1 archive2
  • Create a tarball from an archive:

    borg export-tar /path/to/repo::docs_4nov20 docs_4nov20.tar.gz
  • Verify the consistency of a repository:

    borg check --repository-only -v /path/to/repo
  • Verify the consistency of all archives:

    borg check --archives-only -v /path/to/repo
  • Attempt to repair any inconsistencies found:

    borg check --repair -v /path/to/repo
  • Upgrade local Borg repository to newer version:

    borg upgrade -v /path/to/repo

Key maintenance

If repository encryption is used, the repository is inaccessible without the key. This command allows to backup this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase.
There are two backup formats. The normal backup format is suitable for digital storage as a file. The --paper backup format is optimized for printing and typing in while importing, with per line checks to reduce problems with manual input.
For repositories using keyfile encryption the key is saved locally on the system that is capable of doing backups. To guard against loss of this key, the key needs to be backed up independently of the main data backup.
For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file is damaged for some reason.

  • Export a key:

    borg key export /path/to/repo /path/to/key
  • Import a key:

    borg key import /path/to/repo /path/to/key
  • Change a passphrase for key:

    borg key change-passphrase /path/to/repo

    Please note that this command only changes the passphrase, but not any secret protected by it.

Read more

You can find all borg options in man pages:

man borg

Or check official documentation at

What's on this Page