2013-06-30 19:30:17 +00:00
.. include :: global.rst.inc
.. _installation:
Installation
2013-07-31 18:51:01 +00:00
============
2013-06-30 19:30:17 +00:00
2015-10-16 08:59:38 +00:00
There are different ways to install |project_name|:
2015-11-15 02:03:38 +00:00
- :ref: `distribution-package` - easy and fast if a package is
2015-11-16 03:42:49 +00:00
available from your distribution.
2015-11-15 02:03:38 +00:00
- :ref: `pyinstaller-binary` - easy and fast, we provide a ready-to-use binary file
2015-10-16 08:59:38 +00:00
that comes bundled with all dependencies.
2015-11-15 02:03:38 +00:00
- :ref: `source-install` , either:
2015-08-28 23:17:19 +00:00
2015-11-15 02:03:38 +00:00
- :ref: `pip-installation` - installing a source package with pip needs
more installation steps and requires all dependencies with
development headers and a compiler.
- :ref: `git-installation` - for developers and power users who want to
have the latest code or use revision control (each release is
tagged).
2013-06-30 19:30:17 +00:00
2015-11-15 02:03:38 +00:00
.. _distribution-package:
Distribution Package
--------------------
2014-02-04 02:26:36 +00:00
2015-11-16 03:42:49 +00:00
Some distributions might offer a ready-to-use `` borgbackup ``
2015-10-16 08:59:38 +00:00
package which can be installed with the package manager. As |project_name| is
still a young project, such a package might be not available for your system
2015-11-15 02:07:16 +00:00
yet.
2015-04-27 20:35:06 +00:00
2016-01-13 20:23:34 +00:00
============ ============================================= =======
Distribution Source Command
============ ============================================= =======
Arch Linux `[community]`_ `` pacman -S borg ``
Debian `stretch`_ , `unstable/sid`_ `` apt install borgbackup ``
NixOS `.nix file`_ N/A
OS X `Brew cask`_ `` brew cask install borgbackup ``
Ubuntu `Xenial 16.04`_ , `Wily 15.10 (backport PPA)`_ `` apt install borgbackup ``
============ ============================================= =======
2014-12-16 03:02:43 +00:00
2015-12-01 22:16:25 +00:00
.. _[community]: https://www.archlinux.org/packages/?name=borg
2016-01-13 20:23:34 +00:00
.. _stretch: https://packages.debian.org/stretch/borgbackup
2015-11-16 03:40:00 +00:00
.. _unstable/sid: https://packages.debian.org/sid/borgbackup
2016-01-13 20:23:34 +00:00
.. _Xenial 16.04: https://launchpad.net/ubuntu/xenial/+source/borgbackup
2016-01-13 20:17:54 +00:00
.. _Wily 15.10 (backport PPA): https://launchpad.net/~neoatnhng/+archive/ubuntu/ppa
2016-01-13 20:18:19 +00:00
.. _.nix file: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/backup/borg/default.nix
2015-11-16 03:40:00 +00:00
.. _Brew cask: http://caskroom.io/
2015-11-15 02:07:16 +00:00
Please ask package maintainers to build a package or, if you can package /
submit it yourself, please help us with that! See :issue: `105` on
github to followup on packaging efforts.
2015-10-16 08:59:38 +00:00
If a package is available, it might be interesting to check its version
and compare that to our latest release and review the :doc: `changes` .
2014-12-16 03:02:43 +00:00
2015-11-15 02:03:38 +00:00
.. _pyinstaller-binary:
2013-06-30 19:30:17 +00:00
2015-11-15 19:23:33 +00:00
Standalone Binary
2015-11-15 02:08:28 +00:00
-----------------
2015-09-21 19:28:18 +00:00
2015-11-15 02:08:28 +00:00
|project_name| binaries (generated with `pyinstaller`_ ) are available
on the releases_ page for the following platforms:
2015-09-21 19:28:18 +00:00
2015-10-16 08:59:38 +00:00
* **Linux** : glibc >= 2.13 (ok for most supported Linux releases)
* **Mac OS X** : 10.10 (unknown whether it works for older releases)
* **FreeBSD** : 10.2 (unknown whether it works for older releases)
2015-09-21 19:28:18 +00:00
2015-11-20 14:49:53 +00:00
To install such a binary, just drop it into a directory in your `` PATH `` ,
make borg readable and executable for its users and then you can run `` borg `` ::
sudo cp borg-linux64 /usr/local/bin/borg
sudo chown root:root /usr/local/bin/borg
sudo chmod 755 /usr/local/bin/borg
2016-01-06 12:35:28 +00:00
Note that the binary uses /tmp to unpack |project_name| with all dependencies. It will fail if /tmp has not enough free space or is mounted with the `` noexec `` option. You can change the temporary directory by setting the `` TEMP `` environment variable before running |project_name|.
2015-11-20 14:49:53 +00:00
If a new version is released, you will have to manually download it and replace
the old version using the same steps as shown above.
2015-09-21 19:28:18 +00:00
2015-11-15 02:08:28 +00:00
.. _pyinstaller: http://www.pyinstaller.org
2015-10-16 08:59:38 +00:00
.. _releases: https://github.com/borgbackup/borg/releases
2014-12-16 03:02:43 +00:00
2015-11-15 02:03:38 +00:00
.. _source-install:
2015-11-15 19:23:33 +00:00
From Source
2015-11-15 02:03:38 +00:00
-----------
2014-12-16 03:02:43 +00:00
2015-11-15 02:03:38 +00:00
Dependencies
~~~~~~~~~~~~
To install |project_name| from a source package (including pip), you have to install the
2015-10-16 08:59:38 +00:00
following dependencies first:
2014-12-16 03:02:43 +00:00
2015-10-16 08:59:38 +00:00
* `Python 3`_ >= 3.2.2. Even though Python 3 is not the default Python version on
most systems, it is usually available as an optional install.
* OpenSSL_ >= 1.0.0
* libacl_ (that pulls in libattr_ also)
* liblz4_
* some Python dependencies, pip will automatically install them for you
* optionally, the llfuse_ Python package is required if you wish to mount an
archive as a FUSE filesystem. FUSE >= 2.8.0 is required for llfuse.
2013-06-30 19:30:17 +00:00
2015-10-16 08:59:38 +00:00
In the following, the steps needed to install the dependencies are listed for a
selection of platforms. If your distribution is not covered by these
instructions, try to use your package manager to install the dependencies. On
FreeBSD, you may need to get a recent enough OpenSSL version from FreeBSD
ports.
2013-06-30 19:30:17 +00:00
2015-10-16 08:59:38 +00:00
After you have installed the dependencies, you can proceed with steps outlined
under :ref: `pip-installation` .
2015-08-01 13:07:54 +00:00
2015-10-16 08:59:38 +00:00
Debian / Ubuntu
2015-11-15 02:03:38 +00:00
+++++++++++++++
2013-06-30 19:30:17 +00:00
2015-10-16 08:59:38 +00:00
Install the dependencies with development headers::
2015-05-14 18:47:08 +00:00
2015-12-30 14:06:31 +00:00
sudo apt-get install python3 python3-dev python3-pip python-virtualenv \
libssl-dev openssl \
libacl1-dev libacl1 \
liblz4-dev liblz4-1 \
build-essential
2015-10-16 08:59:38 +00:00
sudo apt-get install libfuse-dev fuse pkg-config # optional, for FUSE support
2015-05-14 18:47:08 +00:00
2015-10-16 08:59:38 +00:00
In case you get complaints about permission denied on `` /etc/fuse.conf `` : on
Ubuntu this means your user is not in the `` fuse `` group. Add yourself to that
group, log out and log in again.
2015-05-14 18:47:08 +00:00
2015-10-16 08:59:38 +00:00
Fedora / Korora
2015-11-15 02:03:38 +00:00
+++++++++++++++
2015-06-15 11:09:39 +00:00
2015-10-16 08:59:38 +00:00
Install the dependencies with development headers::
2015-08-29 01:39:53 +00:00
2015-08-28 23:17:19 +00:00
sudo dnf install python3 python3-devel python3-pip python3-virtualenv
2015-06-15 12:39:04 +00:00
sudo dnf install openssl-devel openssl
sudo dnf install libacl-devel libacl
2015-08-17 15:10:37 +00:00
sudo dnf install lz4-devel
2015-10-16 08:59:38 +00:00
sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support
Mac OS X
2015-11-15 02:03:38 +00:00
++++++++
2015-10-16 08:59:38 +00:00
Assuming you have installed homebrew_, the following steps will install all the
dependencies::
2015-08-01 13:07:54 +00:00
2015-10-16 08:59:38 +00:00
brew install python3 lz4 openssl
pip3 install virtualenv
2015-08-01 13:07:54 +00:00
2015-10-16 08:59:38 +00:00
For FUSE support to mount the backup archives, you need at least version 3.0 of
FUSE for OS X, which is available as a pre-release_.
2015-07-14 19:31:35 +00:00
2015-10-16 08:59:38 +00:00
.. _pre-release: https://github.com/osxfuse/osxfuse/releases
2015-07-14 19:31:35 +00:00
2015-10-16 08:59:38 +00:00
Cygwin
2015-11-15 02:03:38 +00:00
++++++
2015-07-14 19:31:35 +00:00
2015-10-16 08:59:38 +00:00
.. note ::
Running under Cygwin is experimental and has only been tested with Cygwin
(x86-64) v2.1.0.
2015-07-14 19:31:35 +00:00
2015-10-16 08:59:38 +00:00
Use the Cygwin installer to install the dependencies::
2015-07-16 20:40:33 +00:00
2015-08-29 00:55:09 +00:00
python3 python3-setuptools
python3-cython # not needed for releases
binutils gcc-core
libopenssl openssl-devel
2015-08-01 13:07:54 +00:00
liblz4_1 liblz4-devel # from cygwinports.org
2015-08-29 00:55:09 +00:00
git make openssh
2015-07-14 19:31:35 +00:00
2015-10-16 08:59:38 +00:00
You can then install `` pip `` and `` virtualenv `` ::
2015-07-14 19:31:35 +00:00
2015-07-25 16:38:16 +00:00
easy_install-3.4 pip
2015-07-14 19:31:35 +00:00
pip install virtualenv
2015-10-16 08:59:38 +00:00
In case the creation of the virtual environment fails, try deleting this file::
2015-07-25 16:38:16 +00:00
2015-10-16 08:59:38 +00:00
/usr/lib/python3.4/__pycache__/platform.cpython-34.pyc
2015-07-25 16:38:16 +00:00
2015-10-16 08:59:38 +00:00
.. _pip-installation:
2015-07-25 16:38:16 +00:00
2015-11-16 03:20:07 +00:00
Using pip
~~~~~~~~~
2015-08-28 23:17:19 +00:00
2015-10-16 08:59:38 +00:00
Virtualenv_ can be used to build and install |project_name| without affecting
the system Python or requiring root access. Using a virtual environment is
optional, but recommended except for the most simple use cases.
2015-08-29 00:55:09 +00:00
2015-10-16 08:59:38 +00:00
.. note ::
If you install into a virtual environment, you need to **activate** it
first (`` source borg-env/bin/activate `` ), before running `` borg `` .
Alternatively, symlink `` borg-env/bin/borg `` into some directory that is in
your `` PATH `` so you can just run `` borg `` .
This will use `` pip `` to install the latest release from PyPi::
2015-08-29 01:39:53 +00:00
2015-08-29 00:55:09 +00:00
virtualenv --python=python3 borg-env
2015-10-16 08:59:38 +00:00
source borg-env/bin/activate
2015-08-29 00:55:09 +00:00
2015-10-16 08:59:38 +00:00
# install Borg + Python dependencies into virtualenv
2015-09-12 17:26:46 +00:00
pip install 'llfuse<0.41' # optional, for FUSE support
# 0.41 and 0.41.1 have unicode issues at install time
2015-08-29 00:55:09 +00:00
pip install borgbackup
2015-10-16 08:59:38 +00:00
To upgrade |project_name| to a new version later, run the following after
activating your virtual environment::
pip install -U borgbackup
2015-08-29 00:55:09 +00:00
2015-11-15 02:03:38 +00:00
.. _git-installation:
2015-08-28 23:17:19 +00:00
2015-11-16 03:20:07 +00:00
Using git
~~~~~~~~~
2015-08-28 23:17:19 +00:00
2015-08-29 00:55:09 +00:00
This uses latest, unreleased development code from git.
2015-10-13 15:25:52 +00:00
While we try not to break master, there are no guarantees on anything. ::
2015-08-29 01:39:53 +00:00
2015-10-13 15:25:52 +00:00
# get borg from github
git clone https://github.com/borgbackup/borg.git
2015-08-28 23:17:19 +00:00
virtualenv --python=python3 borg-env
source borg-env/bin/activate # always before using!
# install borg + dependencies into virtualenv
pip install sphinx # optional, to build the docs
2015-09-12 17:26:46 +00:00
pip install 'llfuse<0.41' # optional, for FUSE support
# 0.41 and 0.41.1 have unicode issues at install time
2015-08-28 23:17:19 +00:00
cd borg
2015-08-29 00:55:09 +00:00
pip install -r requirements.d/development.txt
2015-08-28 23:17:19 +00:00
pip install -e . # in-place editable mode
# optional: run all the tests, on all supported Python versions
2015-10-16 08:59:38 +00:00
# requires fakeroot, available through your package manager
2015-08-28 23:17:19 +00:00
fakeroot -u tox
2015-10-13 15:25:52 +00:00
.. note :: As a developer or power user, you always want to use a virtual environment.