borgmatic/docs/how-to/upgrade.md

title	eleventyNavigation
How to upgrade borgmatic and Borg	key parent order 📦 Upgrade borgmatic/Borg How-to guides 12

Upgrading borgmatic

In general, all you should need to do to upgrade borgmatic is run the following:

sudo pip3 install --user --upgrade borgmatic

See below about special cases with old versions of borgmatic. Additionally, if you installed borgmatic without using pip3 install --user, then your upgrade process may be different.

Upgrading your configuration

The borgmatic configuration file format is almost always backwards-compatible from release to release without any changes, but you may still want to update your configuration file when you upgrade to take advantage of new configuration options. This is completely optional. If you prefer, you can add new configuration options manually.

If you do want to upgrade your configuration file to include new options, use the borgmatic config generate action with its optional --source flag that takes the path to your original configuration file. If provided with this path, borgmatic config generate merges your original configuration into the generated configuration file, so you get all the newest options and comments.

Here's an example:

borgmatic config generate --source config.yaml --destination config-new.yaml

Prior to version 1.7.15 The command to generate configuration files was generate-borgmatic-config instead of borgmatic config generate.

New options start as commented out, so you can edit the file and decide whether you want to use each one.

There are a few caveats to this process. First, when generating the new configuration file, borgmatic config generate replaces any comments you've written in your original configuration file with the newest generated comments. Second, the script adds back any options you had originally deleted, although it does so with the options commented out. And finally, any YAML includes you've used in the source configuration get flattened out into a single generated file.

As a safety measure, borgmatic config generate refuses to modify configuration files in-place. So it's up to you to review the generated file and, if desired, replace your original configuration file with it.

Upgrading from borgmatic 1.0.x

borgmatic changed its configuration file format in version 1.1.0 from INI-style to YAML. This better supports validation, and has a more natural way to express lists of values. To upgrade your existing configuration, first upgrade to the last version of borgmatic to support converting configuration: borgmatic 1.7.14.

As of version 1.1.0, borgmatic no longer supports Python 2. If you were already running borgmatic with Python 3, then you can upgrade borgmatic in-place:

sudo pip3 install --user --upgrade borgmatic==1.7.14

But if you were running borgmatic with Python 2, uninstall and reinstall instead:

sudo pip uninstall borgmatic
sudo pip3 install --user borgmatic==1.7.14

The pip binary names for different versions of Python can differ, so the above commands may need some tweaking to work on your machine.

Once borgmatic is upgraded, run:

sudo upgrade-borgmatic-config

That will generate a new YAML configuration file at /etc/borgmatic/config.yaml (by default) using the values from both your existing configuration and excludes files. The new version of borgmatic will consume the YAML configuration file instead of the old one.

Now you can upgrade to a newer version of borgmatic:

sudo pip3 install --user borgmatic

Upgrading Borg

To upgrade to a new version of Borg, you can generally install a new version the same way you installed the previous version, paying attention to any instructions included with each Borg release changelog linked from the releases page. Some more major Borg releases require additional steps that borgmatic can help with.

Borg 1.2 to 2.0

New in borgmatic version 1.7.0 Upgrading Borg from 1.2 to 2.0 requires manually upgrading your existing Borg 1 repositories before use with Borg or borgmatic. Here's how you can accomplish that.

Start by upgrading borgmatic as described above to at least version 1.7.0 and Borg to 2.0. Then, rename your repository in borgmatic's configuration file to a new repository path. The repository upgrade process does not occur in-place; you'll create a new repository with a copy of your old repository's data.

Let's say your original borgmatic repository configuration file looks something like this:

repositories:
    - path: original.borg

Change it to a new (not yet created) repository path:

repositories:
    - path: upgraded.borg

Prior to version 1.8.0 This option was found in the location: section of your configuration.

Prior to version 1.7.10 Omit the path: portion of the repositories list.

Then, run the rcreate action (formerly init) to create that new Borg 2 repository:

borgmatic rcreate --verbosity 1 --encryption repokey-blake2-aes-ocb \
    --source-repository original.borg --repository upgraded.borg

This creates an empty repository and doesn't actually transfer any data yet. The --source-repository flag is necessary to reuse key material from your Borg 1 repository so that the subsequent data transfer can work.

The --encryption value above selects the same chunk ID algorithm (blake2) commonly used in Borg 1, thereby making deduplication work across transferred archives and new archives.

If you get an error about "You must keep the same ID hash" from Borg, that means the encryption value you specified doesn't correspond to your source repository's chunk ID algorithm. In that case, try not using blake2:

borgmatic rcreate --verbosity 1 --encryption repokey-aes-ocb \
    --source-repository original.borg --repository upgraded.borg

Read about Borg encryption modes for more details.

To transfer data from your original Borg 1 repository to your newly created Borg 2 repository:

borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
    original.borg --repository upgraded.borg --dry-run
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
    original.borg --repository upgraded.borg
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
    original.borg --repository upgraded.borg --dry-run

The first command with --dry-run tells you what Borg is going to do during the transfer, the second command actually performs the transfer/upgrade (this might take a while), and the final command with --dry-run again provides confirmation of success—or tells you if something hasn't been transferred yet.

Note that by omitting the --upgrader flag, you can also do archive transfers between related Borg 2 repositories without upgrading, even down to individual archives. For more on that functionality, see the Borg transfer documentation.

That's it! Now you can use your new Borg 2 repository as normal with borgmatic. If you've got multiple repositories, repeat the above process for each.