How to Restore Files from a Borg Backup Using the Command Line
Note: You should be comfortable using the command line. If you prefer a graphical, client, look into our Vorta Tutorial instead. These instructions should work on macOS and popular Linux flavors, like Debian, Ubuntu, as well as Red Hat, Fedora and CentOS.
This article assumes that you have set up a backup workflow to a local or remote Borg repository. Now you would like to restore files from it. Borg offers two different ways to restore files. The
borg mount command allows you to browse multiple archives and find exactly the file you are looking for. Due to some overhead from the FUSE mount library, the speed can be slower when restoring a large number of files. This is where
borg extract comes in. If you already know which files you need, it can quickly restore large quantities of data including all metadata.
You should already have Borg installed and know how to use the command line. If you didn’t install Borg yet, have a look at this previous guide.
Step 1 - Set up FUSE
The FUSE library allows mounting arbitrary file systems into user space. It’s available for all popular systems. The official Borg docs have a detailed overview for each system. You will need two parts: the actual FUSE library and Python wrappers for it.
For macOS: First install the FUSE library from Homebrew.
$ brew cask install osxfuse
For Debian/Ubuntu: The FUSE library is available from the main package repository.
$ sudo apt-get install libfuse-dev fuse pkg-config
For Red Hat/CentOS: FUSE is available from the official repository.
$ yum install fuse-devel fuse pkgconfig
Step 2 - Install Python FUSE Bindings (optional)
llfuse package provides Python bindings for FUSE. If you are using the standalone binary of Borg, it already includes FUSE bindings and you can proceed to the next step. If you installed Borg from PyPi, you can install it as follows:
Install Python FUSE library
Be sure to install it into the same Python environment as Borg itself.
$ pip install llfuse
If you installed Borg as user-package using the system Python:
$ pip install --user llfuse
Or you could install it together with Borg
$ pip install borgbackup[fuse]
Step 3 - Validate Installation and Repository
Next make sure everything is installed properly and you have access to the backup repo.
$ borg info firstname.lastname@example.org:repo
You should see output similar to this. If you get an error, be sure that you have access to the repository. If your repo is encrypted, it will also ask you for the password or keyfile.
Repository ID: daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb Location: ssh://email@example.com/./repo Encrypted: Yes (repokey BLAKE2b) Cache: /Users/manu/.cache/borg/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb Security dir: /Users/manu/.config/borg/security/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb ------------------------------------------------------------------------------ Original size Compressed size Deduplicated size All archives: 665.90 MB 577.88 MB 68.41 MB Unique chunks Total chunks Chunk index: 1359 6711
If you installed Borg and llfuse via PIP, you can also validate the packages are installed
$ pip freeze | grep llfuse $ pip freeze | grep borgbackup
Step 4 - Using
borg mount to Browse and Restore Files
borg mount command allows for simple browsing and restoring individual files without their complete metadata. This is great to restore a few documents or images.
First create a new folder as mount point. Since we’re not working with root permissions, we won’t use
/mnt. Instead any empty folder in your home directory will suffice.
$ mkdir borg-mnt
Next mount the whole repository into the newly created folder. This will give us a view of all archives in the repository.
$ borg mount firstname.lastname@example.org:repo borg-mount
If there was no error, you should now see all your archives in the
$ ls -l borg-mount
Depending on the archive names used, the output could look like this.
drwxr-xr-x 1 manu staff 0 Feb 16 12:04 nyx2-test-repo-2019-02-16T12:04:06 drwxr-xr-x 1 manu staff 0 Mar 5 13:12 nyx2-test-repo-2019-03-05T13:12:04 drwxr-xr-x 1 manu staff 0 Mar 19 22:36 nyx2-test-repo-2019-03-19T22:36:07 drwxr-xr-x 1 manu staff 0 Mar 25 23:29 nyx2-test-repo-2019-03-25T23:29:35 drwxr-xr-x 1 manu staff 0 Mar 26 23:02 nyx2-test-repo-2019-03-26T23:01:57 drwxr-xr-x 1 manu staff 0 Mar 27 09:21 nyx2-test-repo-2019-03-27T09:21:42
You can now browse this folder structure and copy the files you need.
Step 5 - Using
borg extract to Bulk Restore Files
FUSE can be slow for a large number of files and it can’t restore metadata. For this reason, Borg includes a second command for fast bulk-restoring –
To use it, you will need to know the precise path and archive name to restore. The
borg mount command can be helpful for this.
Assuming we got the archive name and path from the previous step, a possible
borg extract command could be
$ borg extract \ --dry-run --list \ email@example.com:repo::nyx2-test-repo-2019-02-16T12:04:06 \ /Users/manu/Documents/financial
Due to the
--list arguments this will print a list of files to be restored, but won’t actually restore any files. To actually restore files, remove
The last part of the command gives the path you’re looking to restore. If you pass no paths, then all the data will be restored.
Borg will restore your files to the current working directory. So be sure you are in the right place before running the command for real. To restore all the data from a specific snapshot to the current directory:
$ borg extract \ --list \ firstname.lastname@example.org:repo::nyx2-test-repo-2019-02-16T12:04:06
Hopefully this guide gave you a good overview of possible restore options for Borg. First we looked at installing required FUSE libraries to comfortably browse a whole repository. In addition, we used the
borg extract command to quickly restore many files including their metadata.
If you’re looking to complement your backup workflow with cost-effective offsite backups, also look into BorgBase.com. There is a free tier of 5 GB for life. Paid plan start at $2/month or $.005/GB for larger plans. We also offer custom solutions to enterprise customers. This includes setting up local backup agents or evaluating your whole backup strategy. Contact email@example.com for more.