diff --git a/NEWS b/NEWS index 4422c172..0f64dbd9 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,8 @@ 2.1.4.dev0 * Split out borgmatic installation documentation to its own page, so it's easier to find. + * Switch the default borgmatic installation method from pipx to uv, as uv is faster and used for + borgmatic development. If you'd like to switch, see the documentation for more information: + https://torsion.org/borgmatic/how-to/upgrade/ 2.1.3 * #1175: Add a "files_changed" option for customizing Borg's file modification detection. diff --git a/docs/how-to/install-borgmatic.md b/docs/how-to/install-borgmatic.md index 4327e074..24884b61 100644 --- a/docs/how-to/install-borgmatic.md +++ b/docs/how-to/install-borgmatic.md @@ -6,31 +6,32 @@ eleventyNavigation: order: -1 --- -To install borgmatic, first [install + +### Prerequisites + +Before installing borgmatic, first [install Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least version 1.1. (borgmatic does not install Borg automatically so as to avoid conflicts with existing Borg installations.) -Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root -user (with `sudo`) to make installing borgmatic easier without impacting other -Python applications on your system. If you have trouble installing pipx with -pip, then you can install a system package instead. E.g. on Ubuntu or Debian, -run: +Then, [install uv](https://docs.astral.sh/uv/getting-started/installation/) as +the root user (with `sudo`) to make installing borgmatic easier without +impacting other Python applications on your system. For Debian, there is a +[third-party package for +uv](https://dario.griffo.io/posts/how-to-install-uv-debian/). On Ubuntu, there +is a [snap package](https://snapcraft.io/install/astral-uv/ubuntu). On Arch, you +can just install the `python-uv` package. -```bash -sudo apt update -sudo apt install pipx -``` ### Root install -If you want to run borgmatic on a schedule with privileged access to your -files, then you should install borgmatic as the root user by running the -following commands: +If you want borgmatic to run with privileged access so it can backup your system +files, then install borgmatic as the root user by running the following +commands: ```bash -sudo pipx ensurepath -sudo pipx install borgmatic +sudo uv tool update-shell +sudo uv tool install borgmatic ``` Check whether this worked with: @@ -41,7 +42,7 @@ borgmatic --version ``` If borgmatic is properly installed, that should output your borgmatic version. -And if you'd also like `sudo borgmatic` to work, keep reading! +And if you'd also like `sudo borgmatic` to work as well, keep reading! ### Non-root install @@ -52,8 +53,8 @@ then install borgmatic as a non-root user by running the following commands as that user: ```bash -pipx ensurepath -pipx install borgmatic +uv tool update-shell +uv tool install borgmatic ``` This should work even if you've also installed borgmatic as the root user. @@ -97,7 +98,7 @@ installing borgmatic: #### Etc. * [Ansible role](https://github.com/borgbase/ansible-role-borgbackup) - * [uv tool install](https://docs.astral.sh/uv/) + * [pipx](https://pipx.pypa.io/stable/) ## Next steps diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index 9d3c8539..5de08505 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -5,10 +5,25 @@ eleventyNavigation: parent: How-to guides order: 14 --- -In general, all you should need to do to upgrade borgmatic if you've -[installed it with -pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/) -is to run the following: +In general, all you should need to do to upgrade borgmatic if you've [installed +it with uv](https://docs.astral.sh/uv/) is to run the following: + +```bash +sudo uv tool upgrade borgmatic +``` + +Omit `sudo` if you installed borgmatic as a non-root user. And if you +installed borgmatic *both* as root and as a non-root user, you'll need to +upgrade each installation independently. + + +### Upgrading from other installation methods + +#### pipx + +If you have borgmatic installed with +[pipx](https://pipx.pypa.io/latest/installation/), and you'd like to continue +using pipx, then you can upgrade borgmatic with: ```bash sudo pipx upgrade borgmatic @@ -18,16 +33,30 @@ Omit `sudo` if you installed borgmatic as a non-root user. And if you installed borgmatic *both* as root and as a non-root user, you'll need to upgrade each installation independently. +But if you'd like to switch your borgmatic install from pipx to +[uv](https://docs.astral.sh/uv/), uninstall borgmatic with pipx (`sudo pipx +uninstall borgmatic`) and then [install borgmatic with +uv](https://torsion.org/borgmatic/how-to/install-borgmatic/). + +Either one should work just fine. uv is just faster than pipx and also used for +borgmatic +[development](https://torsion.org/borgmatic/how-to/develop-on-borgmatic/). + + +#### pip install + If you originally installed borgmatic with `sudo pip3 install --user`, you can uninstall it first with `sudo pip3 uninstall borgmatic` and then [install it again with -pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/), +uv](https://torsion.org/borgmatic/how-to/install-borgmatic/), which should better isolate borgmatic from your other Python applications. -But if you [installed borgmatic without pipx or -pip3](https://torsion.org/borgmatic/how-to/install-borgmatic/#other-ways-to-install), -then your upgrade method may be different. +#### Etc. + +If you [some other +way](https://torsion.org/borgmatic/how-to/install-borgmatic/#other-ways-to-install), +then your upgrade method may be different. ### Upgrading your configuration diff --git a/docs/reference/configuration/monitoring/apprise.md b/docs/reference/configuration/monitoring/apprise.md index 17f68965..27b0a7d6 100644 --- a/docs/reference/configuration/monitoring/apprise.md +++ b/docs/reference/configuration/monitoring/apprise.md @@ -12,12 +12,11 @@ us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc." Depending on how you installed borgmatic, it may not have come with Apprise. For instance, if you originally [installed borgmatic with -pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/), +uv](https://torsion.org/borgmatic/how-to/install-borgmatic/), run the following to install Apprise so borgmatic can use it: ```bash -sudo pipx uninstall borgmatic -sudo pipx install borgmatic[Apprise] +sudo uv tool install borgmatic[Apprise] ``` Omit `sudo` if borgmatic is installed as a non-root user.