1.. include:: global.rst.inc 2.. highlight:: bash 3.. _installation: 4 5Installation 6============ 7 8There are different ways to install |project_name|: 9 10- :ref:`distribution-package` - easy and fast if a package is 11 available from your distribution. 12- :ref:`pyinstaller-binary` - easy and fast, we provide a ready-to-use binary file 13 that comes bundled with all dependencies. 14- :ref:`source-install`, either: 15 16 - :ref:`pip-installation` - installing a source package with pip needs 17 more installation steps and requires all dependencies with 18 development headers and a compiler. 19 - :ref:`git-installation` - for developers and power users who want to 20 have the latest code or use revision control (each release is 21 tagged). 22 23.. _distribution-package: 24 25Distribution Package 26-------------------- 27 28Some distributions might offer a ready-to-use ``borgbackup`` 29package which can be installed with the package manager. 30 31.. important:: Those packages may not be up to date with the latest 32 |project_name| releases. Before submitting a bug 33 report, check the package version and compare that to 34 our latest release then review :doc:`changes` to see if 35 the bug has been fixed. Report bugs to the package 36 maintainer rather than directly to |project_name| if the 37 package is out of date in the distribution. 38 39.. keep this list in alphabetical order 40 41============ ============================================= ======= 42Distribution Source Command 43============ ============================================= ======= 44Alpine Linux `Alpine repository`_ ``apk add borgbackup`` 45Arch Linux `[community]`_ ``pacman -S borg`` 46Debian `Debian packages`_ ``apt install borgbackup`` 47Gentoo `ebuild`_ ``emerge borgbackup`` 48GNU Guix `GNU Guix`_ ``guix package --install borg`` 49Fedora/RHEL `Fedora official repository`_ ``dnf install borgbackup`` 50FreeBSD `FreeBSD ports`_ ``cd /usr/ports/archivers/py-borgbackup && make install clean`` 51macOS `Homebrew`_ | ``brew install borgbackup`` (official formula, **no** FUSE support) 52 | **or** 53 | ``brew install --cask macfuse`` (`private Tap`_, FUSE support) 54 | ``brew install borgbackup/tap/borgbackup-fuse`` 55Mageia `cauldron`_ ``urpmi borgbackup`` 56NetBSD `pkgsrc`_ ``pkg_add py-borgbackup`` 57NixOS `.nix file`_ N/A 58OpenBSD `OpenBSD ports`_ ``pkg_add borgbackup`` 59OpenIndiana `OpenIndiana hipster repository`_ ``pkg install borg`` 60openSUSE `openSUSE official repository`_ ``zypper in borgbackup`` 61Raspbian `Raspbian testing`_ ``apt install borgbackup`` 62Ubuntu `Ubuntu packages`_, `Ubuntu PPA`_ ``apt install borgbackup`` 63============ ============================================= ======= 64 65.. _Alpine repository: https://pkgs.alpinelinux.org/packages?name=borgbackup 66.. _[community]: https://www.archlinux.org/packages/?name=borg 67.. _Debian packages: https://packages.debian.org/search?keywords=borgbackup&searchon=names&exact=1&suite=all§ion=all 68.. _Fedora official repository: https://apps.fedoraproject.org/packages/borgbackup 69.. _FreeBSD ports: https://www.freshports.org/archivers/py-borgbackup/ 70.. _ebuild: https://packages.gentoo.org/packages/app-backup/borgbackup 71.. _GNU Guix: https://www.gnu.org/software/guix/package-list.html#borg 72.. _pkgsrc: http://pkgsrc.se/sysutils/py-borgbackup 73.. _cauldron: http://madb.mageia.org/package/show/application/0/release/cauldron/name/borgbackup 74.. _.nix file: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/backup/borg/default.nix 75.. _OpenBSD ports: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/sysutils/borgbackup/ 76.. _OpenIndiana hipster repository: https://pkg.openindiana.org/hipster/en/search.shtml?token=borg&action=Search 77.. _openSUSE official repository: https://software.opensuse.org/package/borgbackup 78.. _Homebrew: https://formulae.brew.sh/formula/borgbackup 79.. _private Tap: https://github.com/borgbackup/homebrew-tap 80.. _Raspbian testing: https://archive.raspbian.org/raspbian/pool/main/b/borgbackup/ 81.. _Ubuntu packages: https://packages.ubuntu.com/xenial/borgbackup 82.. _Ubuntu PPA: https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup 83 84Please ask package maintainers to build a package or, if you can package / 85submit it yourself, please help us with that! See :issue:`105` on 86github to followup on packaging efforts. 87 88**Current status of package in the repositories** 89 90.. start-badges 91 92|Packaging status| 93 94.. |Packaging status| image:: https://repology.org/badge/vertical-allrepos/borgbackup.svg 95 :alt: Packaging status 96 :target: https://repology.org/project/borgbackup/versions 97 98.. end-badges 99 100.. _pyinstaller-binary: 101 102Standalone Binary 103----------------- 104 105.. note:: Releases are signed with an OpenPGP key, see 106 :ref:`security-contact` for more instructions. 107 108|project_name| x86/x64 amd/intel compatible binaries (generated with `pyinstaller`_) 109are available on the releases_ page for the following platforms: 110 111* **Linux**: glibc >= 2.19 (ok for most supported Linux releases). 112 Older glibc releases are untested and may not work. 113* **MacOS**: 10.10 or newer (To avoid signing issues download the file via 114 command line **or** remove the ``quarantine`` attribute after downloading: 115 ``$ xattr -dr com.apple.quarantine borg-macosx64.tgz``) 116* **FreeBSD**: 10.3 (unknown whether it works for older releases) 117 118ARM binaries are built by Johann Bauer, see: https://borg.bauerj.eu/ 119 120To install such a binary, just drop it into a directory in your ``PATH``, 121make borg readable and executable for its users and then you can run ``borg``:: 122 123 sudo cp borg-linux64 /usr/local/bin/borg 124 sudo chown root:root /usr/local/bin/borg 125 sudo chmod 755 /usr/local/bin/borg 126 127Optionally you can create a symlink to have ``borgfs`` available, which is an 128alias for ``borg mount``:: 129 130 ln -s /usr/local/bin/borg /usr/local/bin/borgfs 131 132Note that the binary uses /tmp to unpack |project_name| with all dependencies. 133It will fail if /tmp has not enough free space or is mounted with the ``noexec`` option. 134You can change the temporary directory by setting the ``TEMP`` environment variable before running |project_name|. 135 136If a new version is released, you will have to manually download it and replace 137the old version using the same steps as shown above. 138 139.. _pyinstaller: http://www.pyinstaller.org 140.. _releases: https://github.com/borgbackup/borg/releases 141 142.. _source-install: 143 144From Source 145----------- 146 147.. note:: 148 149 Some older Linux systems (like RHEL/CentOS 5) and Python interpreter binaries 150 compiled to be able to run on such systems (like Python installed via Anaconda) 151 might miss functions required by Borg. 152 153 This issue will be detected early and Borg will abort with a fatal error. 154 155Dependencies 156~~~~~~~~~~~~ 157 158To install |project_name| from a source package (including pip), you have to install the 159following dependencies first: 160 161* `Python 3`_ >= 3.5.0, plus development headers. Even though Python 3 is not 162 the default Python version on most systems, it is usually available as an 163 optional install. 164* OpenSSL_ >= 1.0.0, plus development headers. 165* libacl_ (which depends on libattr_), both plus development headers. 166* We have bundled code of the following packages, but borg by default (see 167 setup.py if you want to change that) prefers a shared library if it can 168 be found on the system (lib + dev headers) at build time: 169 170 - liblz4_ >= 1.7.0 (r129) 171 - libzstd_ >= 1.3.0 172 - libb2_ 173* some Python dependencies, pip will automatically install them for you 174* optionally, the llfuse_ Python package is required if you wish to mount an 175 archive as a FUSE filesystem. See setup.py about the version requirements. 176 177If you have troubles finding the right package names, have a look at the 178distribution specific sections below or the Vagrantfile in the git repository, 179which contains installation scripts for a number of operating systems. 180 181In the following, the steps needed to install the dependencies are listed for a 182selection of platforms. If your distribution is not covered by these 183instructions, try to use your package manager to install the dependencies. On 184FreeBSD, you may need to get a recent enough OpenSSL version from FreeBSD 185ports. 186 187After you have installed the dependencies, you can proceed with steps outlined 188under :ref:`pip-installation`. 189 190Debian / Ubuntu 191+++++++++++++++ 192 193Install the dependencies with development headers:: 194 195 sudo apt-get install python3 python3-dev python3-pip python-virtualenv \ 196 libssl-dev openssl \ 197 libacl1-dev libacl1 \ 198 build-essential 199 sudo apt-get install libfuse-dev fuse pkg-config # optional, for FUSE support 200 201In case you get complaints about permission denied on ``/etc/fuse.conf``: on 202Ubuntu this means your user is not in the ``fuse`` group. Add yourself to that 203group, log out and log in again. 204 205Fedora / Korora 206+++++++++++++++ 207 208Install the dependencies with development headers:: 209 210 sudo dnf install python3 python3-devel python3-pip python3-virtualenv 211 sudo dnf install openssl-devel openssl 212 sudo dnf install libacl-devel libacl 213 sudo dnf install gcc gcc-c++ 214 sudo dnf install redhat-rpm-config # not needed in Korora 215 sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support 216 217openSUSE Tumbleweed / Leap 218++++++++++++++++++++++++++ 219 220Install the dependencies automatically using zypper:: 221 222 sudo zypper source-install --build-deps-only borgbackup 223 224Alternatively, you can enumerate all build dependencies in the command line:: 225 226 sudo zypper install python3 python3-devel \ 227 libacl-devel openssl-devel \ 228 python3-Cython python3-Sphinx python3-msgpack-python \ 229 python3-pytest python3-setuptools python3-setuptools_scm \ 230 python3-sphinx_rtd_theme python3-llfuse gcc gcc-c++ 231 232macOS 233+++++ 234 235When installing via Homebrew_, dependencies are installed automatically. To install 236dependencies manually:: 237 238 brew install python3 openssl zstd lz4 xxhash 239 brew install pkg-config 240 pip3 install virtualenv 241 242For FUSE support to mount the backup archives, you need at least version 3.0 of 243macFUSE, which is available via `Github 244<https://github.com/osxfuse/osxfuse/releases/latest>`__, or Homebrew:: 245 246 brew install --cask macfuse 247 248For OS X Catalina and later, be aware that you must authorize full disk access. 249It is no longer sufficient to run borg backups as root. If you have not yet 250granted full disk access, and you run Borg backup from cron, you will see 251messages such as:: 252 253 /Users/you/Pictures/Photos Library.photoslibrary: scandir: [Errno 1] Operation not permitted: 254 255To fix this problem, you should grant full disk access to cron, and to your 256Terminal application. More information `can be found here 257<https://osxdaily.com/2020/04/27/fix-cron-permissions-macos-full-disk-access/>`__. 258 259FreeBSD 260++++++++ 261Listed below are packages you will need to install |project_name|, its dependencies, 262and commands to make FUSE work for using the mount command. 263 264:: 265 266 pkg install -y python3 openssl fusefs-libs pkgconf 267 pkg install -y git 268 python3 -m ensurepip # to install pip for Python3 269 To use the mount command: 270 echo 'fuse_load="YES"' >> /boot/loader.conf 271 echo 'vfs.usermount=1' >> /etc/sysctl.conf 272 kldload fuse 273 sysctl vfs.usermount=1 274 275 276Windows 10's Linux Subsystem 277++++++++++++++++++++++++++++ 278 279.. note:: 280 Running under Windows 10's Linux Subsystem is experimental and has not been tested much yet. 281 282Just follow the Ubuntu Linux installation steps. You can omit the FUSE stuff, it won't work anyway. 283 284 285Cygwin 286++++++ 287 288.. note:: 289 Running under Cygwin is experimental and has not been tested much yet. 290 291Use the Cygwin installer to install the dependencies:: 292 293 python3 python3-devel python3-setuptools 294 binutils gcc-g++ 295 libopenssl openssl-devel 296 git make openssh 297 298You can then install ``pip`` and ``virtualenv``:: 299 300 easy_install-3.7 pip 301 pip install virtualenv 302 303 304.. _pip-installation: 305 306Using pip 307~~~~~~~~~ 308 309Virtualenv_ can be used to build and install |project_name| without affecting 310the system Python or requiring root access. Using a virtual environment is 311optional, but recommended except for the most simple use cases. 312 313.. note:: 314 If you install into a virtual environment, you need to **activate** it 315 first (``source borg-env/bin/activate``), before running ``borg``. 316 Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in 317 your ``PATH`` so you can just run ``borg``. 318 319This will use ``pip`` to install the latest release from PyPi:: 320 321 virtualenv --python=python3 borg-env 322 source borg-env/bin/activate 323 324 # might be required if your tools are outdated 325 pip install -U pip setuptools wheel 326 # install Borg + Python dependencies into virtualenv 327 pip install borgbackup 328 # or alternatively (if you want FUSE support): 329 pip install borgbackup[fuse] 330 331To upgrade |project_name| to a new version later, run the following after 332activating your virtual environment:: 333 334 pip install -U borgbackup # or ... borgbackup[fuse] 335 336.. _git-installation: 337 338Using git 339~~~~~~~~~ 340 341This uses latest, unreleased development code from git. 342While we try not to break master, there are no guarantees on anything. 343 344:: 345 346 # get borg from github 347 git clone https://github.com/borgbackup/borg.git 348 349 virtualenv --python=python3 borg-env 350 source borg-env/bin/activate # always before using! 351 352 # install borg + dependencies into virtualenv 353 cd borg 354 pip install -r requirements.d/development.txt 355 pip install -r requirements.d/docs.txt # optional, to build the docs 356 pip install -r requirements.d/fuse.txt # optional, for FUSE support 357 pip install -e . # in-place editable mode 358 359 # optional: run all the tests, on all installed Python versions 360 # requires fakeroot, available through your package manager 361 fakeroot -u tox --skip-missing-interpreters 362 363.. note:: As a developer or power user, you always want to use a virtual environment. 364
