- 📥 Set up backups
- 🔀 Make per-application backups
- 🔒 Provide your passwords
- ☁️ Make backups redundant
- 📏 Deal with very large backups
- 🔎 Inspect your backups
- 🚨 Monitor your backups
- 📤 Extract a backup
- 🗄️ Backup your databases
- 🧹 Add preparation and cleanup steps
- 💾 Backup to a removable drive/server
- 🔧 Run arbitrary Borg commands
- 📦 Upgrade borgmatic/Borg
- 🏗️ Develop on borgmatic
- Reference guides
Many users need to backup system files that require privileged access, so these instructions install and run borgmatic as root. If you don't need to backup such files, then you are welcome to install and run borgmatic as a non-root user.
First, manually install Borg, at least version 1.1. borgmatic does not install Borg automatically so as to avoid conflicts with existing Borg installations.
Then, download and install borgmatic as a user site installation by running the following command:
sudo pip3 install --user --upgrade borgmatic
This installs borgmatic and its commands at the
Your pip binary may have a different name than "pip3". Make sure you're using Python 3.7+, as borgmatic does not support older versions of Python.
The next step is to ensure that borgmatic's commands available are on your
PATH, so that you can run borgmatic:
echo export 'PATH="$PATH:/root/.local/bin"' >> ~/.bashrc
/root/.local/bin to your non-root user's system
If you're using a command shell other than Bash, you may need to use different commands here.
You can check whether all of this worked with:
sudo borgmatic --version
If borgmatic is properly installed, that should output your borgmatic version.
As an alternative to adding the path to
~/.bashrc file, if you're using sudo
to run borgmatic, you can configure sudo's
secure_path option to include
Global install option
If you try the user site installation above, and have problems making
borgmatic commands runnable on your system
PATH, an alternate approach is to
install borgmatic globally.
The following uninstalls borgmatic, and then reinstalls it such that borgmatic
commands are on the default system
sudo pip3 uninstall borgmatic
sudo pip3 install --upgrade borgmatic
The main downside of a global install is that borgmatic is less cleanly separated from the rest of your Python software, and there's the theoretical possibility of library conflicts. But if you're okay with that, for instance on a relatively dedicated system, then a global install can work out fine.
Other ways to install
Besides the approaches described above, there are several other options for installing borgmatic:
- Docker image with scheduled backups (+ Docker Compose files)
- Docker image with multi-arch and Docker CLI support
- Fedora official
- Fedora unofficial
- Arch Linux
- Alpine Linux
- macOS (via Homebrew)
- Ansible role
Need somewhere to store your encrypted off-site backups? The following hosting providers include specific support for Borg/borgmatic—and fund borgmatic development and hosting when you use these links to sign up. (These are referral links, but without any tracking scripts or cookies.)
- BorgBase: Borg hosting service with support for monitoring, 2FA, and append-only repos
Additionally, rsync.net and Hetzner have compatible storage offerings, but do not currently fund borgmatic development or hosting.
After you install borgmatic, generate a sample configuration file:
If that command is not found, then it may be installed in a location that's
not in your system
PATH (see above). Try looking in
This generates a sample configuration file at
default. If you'd like to use another path, use the
--destination flag, for
You should edit the configuration file to suit your needs, as the generated values are only representative. All options are optional except where indicated, so feel free to ignore anything you don't need.
Note that the configuration file is organized into distinct sections, each
with a section name like
storage:. So take care that if you
uncomment a particular option, also uncomment its containing section name, or
else borgmatic won't recognize the option. Also be sure to use spaces rather
than tabs for indentation; YAML does not allow tabs.
You can get the same sample configuration file from the configuration reference, the authoritative set of all configuration options. This is handy if borgmatic has added new options since you originally created your configuration file. Also check out how to upgrade your configuration.
If you encrypt your Borg repository with a passphrase or a key file, you'll
either need to set the borgmatic
variable or set the
BORG_PASSPHRASE environment variable. See the
of the Borg Quick Start for more info.
Alternatively, you can specify the passphrase programatically by setting
either the borgmatic
encryption_passcommand configuration variable or the
BORG_PASSCOMMAND environment variable. See the Borg Security
for more info.
If you'd like to configure your backups to go to multiple different repositories, see the documentation on how to make backups redundant.
If you'd like to validate that your borgmatic configuration is valid, the following command is available for that:
This command's exit status (
$? in Bash) is zero when configuration is valid
and non-zero otherwise.
Validating configuration can be useful if you generate your configuration files via configuration management, or you want to double check that your hand edits are valid.
Before you can create backups with borgmatic, you first need to create a Borg repository so you have a destination for your backup archives. (But skip this step if you already have a Borg repository.) To create a repository, run a command like the following with Borg 1.x:
sudo borgmatic init --encryption repokey
Or, with Borg 2.x:
sudo borgmatic rcreate --encryption repokey-aes-ocb
repokey-chacha20-poly1305 may be faster than
certain platforms like ARM64.)
This uses the borgmatic configuration file you created above to determine which local or remote repository to create, and encrypts it with the encryption passphrase specified there if one is provided. Read about Borg encryption modes for the menu of available encryption modes.
Also, optionally check out the Borg Quick Start for more background about repository creation.
Note that borgmatic skips repository creation if the repository already exists. This supports use cases like ensuring a repository exists prior to performing a backup.
If the repository is on a remote host, make sure that your local user has key-based SSH access to the desired user account on the remote host.
Now that you've configured borgmatic and created a repository, it's a good idea to test that borgmatic is working. So to run borgmatic and start a backup, you can invoke it like this:
sudo borgmatic create --verbosity 1 --list --stats
--list flag? Try
--files instead, leave it out, or upgrade
--verbosity flag makes borgmatic show the steps it's performing. The
--list flag lists each file that's new or changed since the last backup. And
--stats shows summary information about the created archive. All of these
flags are optional.
As the command runs, you should eyeball the output to see if it matches your expectations based on your configuration.
If you'd like to specify an alternate configuration file path, use the
borgmatic --help and
borgmatic create --help for more information.
If you omit
create and other actions, borgmatic runs through a set of
prune any old backups as per the configured retention
compact segments to free up space (with Borg 1.2+),
check backups for consistency problems due to things like file
damage. For instance:
sudo borgmatic --verbosity 1 --list --stats
Running backups manually is good for validating your configuration, but I'm guessing that you want to run borgmatic automatically, say once a day. To do that, you can configure a separate job runner to invoke it periodically.
If you're using cron, download the sample cron file. Then, from the directory where you downloaded it:
sudo mv borgmatic /etc/cron.d/borgmatic
sudo chmod +x /etc/cron.d/borgmatic
If borgmatic is installed at a different location than
/root/.local/bin/borgmatic, edit the cron file with the correct path. You
can also modify the cron file if you'd like to run borgmatic more or less
If you're using systemd instead of cron to run jobs, you can still configure borgmatic to run automatically.
(If you installed borgmatic from Other ways to install, you may already have borgmatic systemd service and timer files. If so, you may be able to skip some of the steps below.)
First, download the sample systemd service file and the sample systemd timer file.
Then, from the directory where you downloaded them:
sudo mv borgmatic.service borgmatic.timer /etc/systemd/system/
sudo systemctl enable --now borgmatic.timer
Review the security settings in the service file and update them as needed.
ProtectSystem=strict is enabled and local repositories are used, then
the repository path must be added to the
Feel free to modify the timer file based on how frequently you'd like borgmatic to run.
launchd in macOS
If you run borgmatic in macOS with launchd, you may encounter permissions issues when reading files to backup. If that happens to you, you may be interested in an unofficial work-around for Full Disk Access.
borgmatic includes a shell completion script (currently only for Bash) to
support tab-completing borgmatic command-line actions and flags. Depending on
how you installed borgmatic, this may be enabled by default. But if it's not,
start by installing the
bash-completion Linux package or the
macOS Homebrew formula. Then, install the shell completion script globally:
sudo su -c "borgmatic --bash-completion > $(pkg-config --variable=completionsdir bash-completion)/borgmatic"
If you don't have
pkg-config installed, you can try the following path
sudo su -c "borgmatic --bash-completion > /usr/share/bash-completion/completions/borgmatic"
Or, if you'd like to install the script for only the current user:
mkdir --parents ~/.local/share/bash-completion/completions
borgmatic --bash-completion > ~/.local/share/bash-completion/completions/borgmatic
Finally, restart your shell (
exit and open a new shell) so the completions
borgmatic produces colored terminal output by default. It is disabled when a
non-interactive terminal is detected (like a cron job), or when you use the
--json flag. Otherwise, you can disable it by passing the
setting the environment variable
PY_COLORS=False, or setting the
false in the
output section of configuration.
"found character that cannot start any token" error
If you run borgmatic and see an error looking something like this, it probably means you've used tabs instead of spaces:
test.yaml: Error parsing configuration file An error occurred while parsing a configuration file at config.yaml: while scanning for the next token found character that cannot start any token in "config.yaml", line 230, column 1
YAML does not allow tabs. So to fix this, replace any tabs in your configuration file with the requisite number of spaces.
libyaml compilation errors
borgmatic depends on a Python YAML library (ruamel.yaml) that will optionally use a C YAML library (libyaml) if present. But if it's not installed, then when installing or upgrading borgmatic, you may see errors about compiling the YAML library. If so, not to worry. borgmatic should install and function correctly even without the C YAML library. And borgmatic won't be any faster with the C library present, so you don't need to go out of your way to install it.
Improve this documentation
Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!