Getting started with Borg

Learn the basics of Borg: install, backup, restore.

• For: someone who has never used Borg.
• Before you start: a Linux or Mac machine, a USB stick or a folder to back up to, and the terminal (see Terminal basics).
• Reading time: about 7 minutes.
• You end with: Borg installed, one encrypted backup made, and one restore done and checked.

1. Install Borg

Note

OS: Borg runs on Mac and Linux, not Windows directly. Windows users, what are you still doing there? Choosing the OS is the way out. If you really cannot migrate away from Windows, you can run Borg through WSL (Windows Subsystem for Linux): install WSL, then follow the Linux steps below inside it.

Video demo: If you prefer first watching a demo on how Borg works, see the official demo. It’s old but good.

On Debian-based Linux

sudo apt install borgbackup -y

On macOS

Install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

When Homebrew finishes it prints a couple of lines starting with eval or export that tell you how to finish setup; copy those, paste them in, and press Enter. Then install Borg:

brew analytics off
brew install borgbackup

On an airgapped machine

To install on a Debian-based airgapped computer, see this guide.

Whichever route you took, run borg --version; if it prints a version number, you’re ready.

2. Create the repo

Borg calls the backup folder a repository: an encrypted, compressed container that holds your data. You have to do this step only once per drive unless, of course, you lose or damage your drive.

2.1. Get the path to your drive

Plug in your external drive or USB stick, and find the path to it.

Note

On macOS: It appears at /Volumes/your-label. To read the exact path on a Mac, open the drive in Finder, press Cmd + Opt + C to copy it as a pathname, and paste it anywhere; you will see something like /Volumes/your-usb-label; e.g. /Volumes/backup1.

On Linux: It usually appears at /media/your-name/your-usb-label; e.g. /media/john/backup1/.

Tip

If you have no spare drive, you can still test Borg by using a folder on your system, say ~/Documents. But note that the whole point of backing up to a drive is so that if your laptop fails or gets stolen, your backup is not lost with it.

2.2. Name and create the repo

Name the repo anything you like, and run the command to create the repo (after editing the path and repo name to match yours):

borg init --encryption=repokey /Volumes/backup1/borg

On Linux that path should look something like /media/john/backup1/borg. And if you are testing Borg on your system, then it should look something like ~/Documents/borg.

2.3. Enter the passphrase twice

Pick a strong one. For tips on creating a secure passphrase, see Creating passphrases. When it asks whether to show the passphrase for verification, type n. Borg then prints a block that starts IMPORTANT: you will need both KEY AND PASSPHRASE to access this repo!; on Borg 1.2 a paragraph about older Borg versions comes before it. Both are normal, and the repo is ready.

Caution

Write this passphrase on paper and keep it somewhere away from the laptop. Borg needs both the key and the passphrase to open the repo. With repokey the key is stored in the repo itself, so the passphrase is the one you have to keep: lose it, and your backups are gone for good, with no reset.

That’s it. That’s the whole one-time setup with Borg. From here on, unless you lose your drive, it’s just one command per drive to back up (well, two if you count the cd); and two to restore. If you level up and start using scripts, then it’s one command to back up to all your drives; and one command to restore from any one of them. See Levelling up for details.

If you keep a second drive labelled backup2, set it up and back up the same way (borg init --encryption=repokey /Volumes/backup2/borg); just change backup1 to backup2 in the path.

3. Back up

Note

From here, every command below uses /Volumes/backup1/borg; replace it with your own path.

Using the terminal, navigate to the folder that contains the folder you want to back up. Say the folder you want to back up is mystuff and it lives in your Documents folder, run:

cd ~/Documents && borg create -s /Volumes/backup1/borg::{now} mystuff

Borg asks Enter passphrase for key followed by the repo’s path, here and every time it opens the repo; as with sudo, nothing shows while you type. Congratulations. You’ve successfully backed up your folder to your Borg repo. You should see something like this.

Note

If you run create with the full path, ~/Documents/mystuff, Borg backs up the whole path, such that when you extract you get the whole tree home/<user>/Documents/mystuff. While if you cd to the parent and give just the folder’s name, as above, then extract gives you just the folder you backed up. Borg 1.4 and newer can do the same from anywhere with the slashdot hack, ~/Documents/./mystuff; older Borg, which Ubuntu 24.04 and Linux Mint 22 still ship, ignores the /./ without a word.

{now} names this backup with the date and time you make the backup, so each backup stays separate. If you would rather name it yourself, swap {now} for anything; e.g. ::archive. Borg requires archive names within the same repository to be unique. If you try to create a new archive with an existing name, Borg will fail with the error Archive <archive-name> already exists. This is by design because each archive is an immutable snapshot. Those who back up more than one machine commonly use ::{hostname}-{now} so each machine’s backups are labelled and sort together; for one folder on one machine, {now} is all you need.

-s stands for stats, shown in the image above. You may remove that if you don’t care about it.

The first backup copies everything, so it takes a while: roughly two to three minutes for 10 GB to a fast external drive, and longer, ten minutes or more, to a cheap USB stick. After that Borg remembers what it already saved and only adds what changed, so every backup after the first is usually done in seconds to a minute.

Tip

If you do not use the terminal a lot, the next time you want to make a backup, you do not have to retype the command: plug in the drive, wait for it to mount, open the terminal, press the up arrow until the borg create line appears, and press Enter. The cd is on the same line, so it comes back with it; from any other folder Borg wouldn’t find mystuff and would save an empty archive.

Important

Back up after every change you care about. You could also back up on a schedule you will actually keep, once a day or once a week, but definitely before you switch or wipe a laptop.

Keep one of your drives somewhere else: at work, with family, or in a safe. Two drives in the same drawer both die in the same fire or theft; the one stored elsewhere is the one that saves you.

4. Restore

4.1. Select archive

First get the list of archives. From anywhere on the terminal, run the command:

borg list /Volumes/backup1/borg

This produces a list of every backup you have made, with the latest at the bottom. If you used {now} as your archive name, each line starts with a timestamp like 2026-05-09T19:15:31. Usually the latest archive is the one you want; older ones matter when the latest is damaged, or when you deleted or changed a file before your last backup and want it back as it was.

Copy the archive name (which in this case is the timestamp) of the backup you want from the list.

4.2. Extract

Navigate to wherever you want to extract your backup; e.g. Downloads. Then paste your timestamp in place of the one shown:

cd ~/Downloads
borg extract --progress /Volumes/backup1/borg::2026-05-09T19:15:31

--progress first prints Calculating total archive size for the progress indicator, then a running percentage. When it finishes, ls shows your folder, mystuff, in Downloads. Congratulations. And that’s how easy it is to use Borg.

Tip

If you want to extract just one file or folder from the archive, instead of extracting the whole archive, extract only the file using borg extract repo::archive-name path/to/file; for example borg extract --progress /Volumes/backup1/borg::2026-05-09T19:15:31 mystuff/test-file.md. The path is the one inside the archive, so it starts with the folder’s name; borg list /Volumes/backup1/borg::2026-05-09T19:15:31 shows every path.

5. Verify extracts

You’ve learnt how to make a backup and restore it, all good, but that’s not the same as being sure of what the archive holds rather than what you think it holds. Borg will not tell you that. A mistyped path, a folder you meant to include and did not, an exclude that caught more than you intended: each of those produces a clean backup but is quietly missing things. There is no warning, because from Borg’s side nothing went wrong.

So before you delete anything, or start relying on this, spend a few minutes checking. Do it straight after making an archive and extracting, while the source has not changed underneath you. Open the last saved file, and check if the contents are present. To check every file at once, compare the restored folder with the original: diff -r ~/Documents/mystuff ~/Downloads/mystuff. If it prints nothing, every file came back exactly as it was; anything it prints is a file that’s missing or different.

If you have a spare or second machine, restore the backup there; or use a fresh user account, with nothing but the drive and the passphrase. That is the situation you are trying to guard yourself against, yet that is where many find out that the only copy of the passphrase they had was on the machine that died. So don’t skip this step. Test it at least once while nothing is wrong, so you’re confident of restoring from backup on a new system.

When your restore checks out, move on to Planning: the decisions the tool won’t make for you.