Skip to content

How to Set Up Borg Backups from the Command Line on Linux and macOS

Reviewed in May 2026

In this article we will set up a backup software called Borg Backup (or Borg for short). There are other backup solutions for Linux or macOS, but Borg has all the features we would expect from a proper backup, like encryption, compression and deduplication.

This tutorial assumes you are using a recent Linux, *BSD or macOS machine. The instructions should work on macOS and popular Linux flavors, like Debian, Ubuntu, as well as Red Hat, Fedora and CentOS. You don’t need to be a command line expert. All commands can be copy & pasted.

It also assumes that you have a server-based version of Borg available. The easiest option is to sign up for BorgBase.com, which offers a free tier of 10 GB. Other options are your own server with SSH access or one of the providers linked here.

In this step we will install Borg Backup. There are many ways to install Borg. Here just the most common ones. For more details, look at the Borg installation guide.

Most distributions and Homebrew include Borg 1.x. The packaged version can lag behind the latest release.

Terminal window
$ sudo apt install borgbackup # Debian, Ubuntu
$ sudo dnf install borgbackup # Fedora, RHEL
$ brew install borgbackup # macOS

That’s it. You now have Borg installed on your local machine. You can test it by simply starting it and checking the version

Terminal window
$ borg --version

This should print something like borg 1.4.5.

Step 2 – Create and Assign SSH Key for Authentication

Section titled “Step 2 – Create and Assign SSH Key for Authentication”

In this step we will securely connect your machine to the remote repository using a SSH key. If you manage your own server or have already set SSH up, you can skip this step.

Let’s start by generating a public-private key pair based on the (currently) most secure Ed25519 standard.

Terminal window
$ ssh-keygen -o -a 100 -t ed25519

This will ask you for a location to save the key and a password. If you want to use automatic backups, you should enter an empty passphrase or add the passphrase to the macOS Keychain.

The private key should remain a secret on your local machine. The public key is passed to your remote/cloud backup repository. You can display the public key using this command:

Terminal window
$ cat ~/.ssh/id_ed25519.pub

Now just copy it and provide it to your repository provider. When using BorgBase.com, you can add public keys under Account > SSH Keys. For supported key types and more background, see SSH Keys for BorgBase.

Step 3 – Create a Remote Borg Repository

Section titled “Step 3 – Create a Remote Borg Repository”

After adding your public key, you are ready to set up a remote repository. Different providers have different ways for this. When using BorgBase, add a new repository under Repositories. It will ask for a repo name, quota and which SSH key to use. You can also choose between US and EU server locations.

After adding the repo, you can copy the repository location using the icon in the first Name column.

This will tell Borg where to connect to for storing backups and it will use your public SSH key to authenticate itself. There are no passwords to remember and it’s very difficult to crack a key due to its length.

The URL format depends on the Borg version chosen for the repository:

Borg version Repository URL
Borg 1.x ssh://xxx@xxx.repo.borgbase.com/./repo
Borg 2.x ssh://xxx@xxx.repo.borgbase.com/repo

Step 4 – Initialize Repository and Run a First Backup

Section titled “Step 4 – Initialize Repository and Run a First Backup”

Now that we have a secure connection to our repository, we can start using it. The first step is to initialize it. This involves setting an encryption mode and password.

Borg can keep the encryption key in two places. repokey means that the key is protected by a password and stored in the remote backup repo. There is also keyfile, which stores the key in your home-folder. It’s important to know that both the key and the password are required to access a repo. So if you lose your laptop with the keyfile on it, you can’t access the backup. That’s why it’s important to either use repokey or keep a copy of the keyfile somewhere else.

To initialize the remote repo, use the commands below. Replace the ssh:// URL with your actual full repository address given in the control panel. The repository URL will be kept as BORG_REPO variable to avoid typing it each time.

Terminal window
$ export BORG_REPO=ssh://xxx@xxx.repo.borgbase.com/./repo
$ borg init -e repokey-blake2

All those commands will ask you for a passphrase to protect the repository key. Make it nice and long and keep it somewhere safe.

After the command is done, you have your remote backup repository set up and ready to accept files. You can add some test files from your Documents folder with this command:

Terminal window
$ borg create ::my-archive-1 ~/Documents

my-archive-1 is the archive name. It needs to be unique, so mostly people use the hostname and a timestamp. E.g. tim-macbook-2018-10-10.

Archives allow you to access different versions of your files. This can be useful if a file was deleted by accident or encrypted by a cryptolocker.

Step 5 – Set up Borgmatic for Regular Backups

Section titled “Step 5 – Set up Borgmatic for Regular Backups”

After completing the previous steps, you are ready to use Borg for simple operations. It would be quite cumbersome to manually run Borg every few hours and keep track of excluded files and old archives. That’s why we will use a helper tool – Borgmatic – to do this job for us.

Borgmatic is written in Python and there is no pre-compiled binary. The recommended way to install it is uv, which keeps it separate from other Python packages on your system. For system-wide backups, install it as root:

Terminal window
$ sudo uv tool update-shell
$ sudo uv tool install borgmatic

If you plan on only backing up your home folder, installing it as your own user will work too:

Terminal window
$ uv tool update-shell
$ uv tool install borgmatic

Many distributions also offer a borgmatic package, though it can be considerably older. See the Borgmatic installation guide for all options.

Let’s start by creating a default Borgmatic folder:

Terminal window
$ mkdir -p ~/.config/borgmatic

Then open the main config file with your favorite text editor. I’ll use nano, but any other editor will work too.

Terminal window
$ nano ~/.config/borgmatic/config.yaml

If you keep your repos with BorgBase you can copy a pre-made Borgmatic configuration from the Setup page. Or start with this version and fill in the blanks:

~/.config/borgmatic/config.yaml
source_directories:
- ~/Desktop
- ~/Documents
- ~/Pictures
# one_file_system: true
repositories:
# For Borg 2 repositories, use ssh://.../repo (without the /./ part)
- path: ssh://mmvz9gp4@mmvz9gp4.repo.borgbase.com/./repo
exclude_caches: true
compression: auto,zstd
encryption_passphrase: CHANGE ME!!
# Number of times to retry a failing backup
retries: 5
retry_wait: 5
keep_daily: 3
keep_weekly: 4
keep_monthly: 12
# Don't read whole repo each time
checks:
- name: repository
frequency: 4 weeks

Let’s look at the major options of this file one-by-one. Since the format is YAML, white-space, like spaces is important.

  • source_directories: The list of folders you actually want to back up. You can always add more source folders later. They will simply be added.
  • repositories: The address of your backup repo.
  • encryption_passphrase: The password to access the repo, as set in step 4.
  • keep_*: Determines how many snapshots Borg will keep.
  • checks: How often Borgmatic verifies the repository. Reading all repo data takes time, so this is limited to once every four weeks.

Archive names are chosen by Borgmatic. By default it uses the hostname and a timestamp with Borg 1 and just the hostname (as series name) with Borg 2. Set archive_name_format to change this.

Once you are happy with the options, save the file and check it for errors:

Terminal window
$ borgmatic config validate

If you already initialized the repository in step 4, skip the next command. Otherwise you can also initialize it via Borgmatic, like you would with Borg only:

Terminal window
$ borgmatic repo-create --encryption repokey-blake2

Run borgmatic create to create a new backup. We will add the --verbosity option to see what’s going on during the first backup.

Terminal window
$ borgmatic --verbosity 2 create

Depending on your backup folder size, this may take a while. After Borgmatic is done, you can view the available snapshots and some statistics.

Terminal window
$ borgmatic repo-list repo-info

After a few seconds you should get some output similar to this (shown for Borg 1.x, the output of Borg 2 is structured differently):

nyx2.local-2018-10-06T11:17:51 Sat, 2018-10-06 11:17:58 [6fa5db68d...aef3ea]
nyx2.local-2018-10-09T12:31:35 Tue, 2018-10-09 12:31:43 [6fa5db68d...aef3ea]
Repository ID: a59c22b17eeb4e9798...987d2f26873c
Location: ssh://mmvz9gp4@mmvz9gp4.repo.borgbase.com/./repo
Encrypted: Yes (repokey)
Cache: /Users/manu/.cache/borg/a59c22b17eeb...d2f26873c
Security dir: /Users/manu/.config/borg/security/a59c22b17e...2f26873c
------------------------------------------------------------------------------
Original size Compressed size Deduplicated size
All archives: 134.41 GB 92.98 GB 7.17 GB
Unique chunks Total chunks
Chunk index: 25309 349526

You can see that there are 2 snapshots in this repository with a total of 134 GB of data. After compression the files were 92 GB and after deduplication only 7 GB. The reason for this difference is that every snapshot includes the same data, so there is a lot of potential for deduplication.

With Borgmatic working, we can set up Cron to do regular backups in the future. Cron is an old Unix tool to run repeated tasks. It’s usually included in all Unix-like systems.

Terminal window
$ crontab -e

This will open an editor to add new cron jobs. There are many ways to schedule cron-jobs. For hourly backups enter this:

@hourly borgmatic

This will run borgmatic every hour. Without further arguments, it creates a new backup, prunes old archives, compacts the repository and runs any checks that are due. You could also schedule it every 3 hours, always 10 minutes after the full hour:

10 */3 * * * borgmatic

Cron uses a minimal PATH. If the job doesn’t find borgmatic, use the full path instead, as printed by which borgmatic.

On Linux systems using systemd, you can use a timer instead of Cron. Borgmatic provides sample unit files for this here.

When you’re done, save the file and you should be set. You can always make sure backups actually happen using the borgmatic repo-list command or by setting a monitoring alert on BorgBase.com. It will alert you if no new snapshots are added for a set amount of time.

You now have a reliable and secure backup setup. Borg and Borgmatic offer many other options. As next steps you can:

  • Export your repokey to keep it secure somewhere. It’s also possible to print it.
  • Learn more about available compression options to see what works well with your data. $ borg help compression
  • View all available Borgmatic options, like excluding certain files.
  • Set up a local backup repository to backup to a hard drive or thumb drive. This is not a replacement for a cloud backup, but does provide some protection against failed hardware if the size of the data is too large to upload.
  • Verify that your backups work and try a test restore.