This documentation is for the latest stable (0.9.3) release of Fabric. To view documentation for the in-development (1.0) version, please click here.
Fabric is best installed via pip (highly recommended) or easy_install (older, but still works fine). You may also opt to use your operating system’s package manager (the package is typically called fabric or python-fabric), or execute python setup.py install inside a downloaded or cloned copy of the source code.
In order for Fabric’s installation to succeed, you will need four primary pieces of software:
- the Python programming language;
- the setuptools packaging/installation library;
- the PyCrypto cryptography library;
- and the Paramiko SSH2 library.
Please read on for important details on each dependency – there are a few gotchas.
Fabric requires Python version 2.5 or 2.6. Some caveats and notes about other Python versions:
- We are not planning on supporting Python 2.4 given its age and the number of useful tools in Python 2.5 such as context managers and new modules. That said, the actual amount of 2.5-specific functionality is not prohibitively large, and we would link to – but not support – a third-party 2.4-compatible fork. (No such fork exists at this time, to our knowledge.)
- Fabric has not yet been tested on Python 3.x and is thus likely to be incompatible with that line of development. However, we try to be at least somewhat forward-looking (e.g. using print() instead of print) and will definitely be porting to 3.x in the future once our dependencies do.
Setuptools comes with some Python installations by default; if yours doesn’t, you’ll need to grab it. In such situations it’s typically packaged as python-setuptools, py25-setuptools or similar. Fabric may drop its setuptools dependency in the future, or include alternative support for the Distribute project, but for now setuptools is required for installation.
PyCrypto is a dependency of Paramiko which provides the low-level (C-based) encryption algorithms used to run SSH. There are a couple gotchas associated with installing PyCrypto: its compatibility with Python’s package tools, and the fact that it is a C-based extension.
Current best practices in the Python packaging world involve using the pip tool, which in most cases offers significant advantages over the older but more common easy_install. Unfortunately, at the time of writing, recent versions of PyCrypto (2.1 and above) conflict with pip and do not install correctly, under Python 2.5. (Thankfully, the problem does not appear to affect Python 2.6.)
Fabric and Paramiko will work correctly with any PyCrypto 1.9 or newer, and PyCrypto 2.0.1 installs just fine via pip. As such, Fabric’s packaging settings are currently set to require PyCrypto 2.0.1 if you’re on Python 2.5.x.
However, Fabric will work fine with PyCrypto 2.1 and up – you’ll just need to upgrade it, via easy_install, after installing Fabric itself.
Unless you are installing from a precompiled source such as a Debian apt repository or RedHat RPM, or using pypm, you will also need the ability to build Python C-based modules from source in order to install PyCrypto. Users on Unix-based platforms such as Ubuntu or Mac OS X will need the traditional C build toolchain installed (e.g. Developer Tools / XCode Tools on the Mac, or the build-essential package on Ubuntu or Debian Linux – basically, anything with gcc, make and so forth) as well as the Python development libraries, often named python-dev or similar.
For Windows users we recommend using ActivePython and PyPM, installing a C development environment such as Cygwin or obtaining a precompiled Win32 PyCrypto package from voidspace’s Python modules page.
Some Windows users whose Python is 64-bit have found that the PyCrypto dependency winrandom may not install properly, leading to ImportErrors. In this scenario, you’ll probably need to compile winrandom yourself via e.g. MS Visual Studio. See #194 for info.
If you are interested in doing development work on Fabric (or even just running the test suite), you may also need to install some or all of the following packages:
- git and Mercurial, in order to obtain some of the other dependencies below;
For an up-to-date list of exact testing/development requirements, including version numbers, please see the requirements.txt file included with the source distribution. This file is intended to be used with pip, e.g. pip install -r requirements.txt.
To obtain a tar.gz or zip archive of the Fabric source code, you may visit either of the following locations:
- The official downloads are located in Fabric’s Redmine instance at http://code.fabfile.org/projects/fabric/files/. This is the spot you want to download from for operating system packages, as the only changing part of the URL will be the filename itself and the md5 hashes will be consistent.
- Our Git repository viewer provides downloads of all tagged releases. See the “Download” column, next to the “Tag” column in the middle of the front page. Please note that due to how cgit generates tag archives, the md5 sums will change over time, so use of this location for package downloads is not recommended.
- Our GitHub mirror also has downloads of all tagged releases – just click the ‘Download’ button near the top of the main page.
- Fabric’s PyPI page offers manual downloads in addition to being the entry point for easy-install.
Source code checkouts¶
The Fabric developers manage the project’s source code with the Git DVCS. To follow Fabric’s development via Git instead of downloading official releases, you have the following options:
- Clone the canonical Git repository, git://fabfile.org/fabric.git (note that a Web view of this repository can be found at git.fabfile.org)
- Clone the official Github mirror/collaboration repository, git://github.com/bitprophet/fabric.git
- Make your own fork of the Github repository by making a Github account, visiting GitHub/bitprophet/fabric and clicking the “fork” button.
If you’ve obtained the Fabric source via source control and plan on updating your checkout in the future, we highly suggest using python setup.py develop instead – it will use symbolic links instead of file copies, ensuring that imports of the library or use of the command-line tool will always refer to your checkout.
For information on the hows and whys of Fabric development, including which branches may be of interest and how you can help out, please see the Development page.
ActivePython and PyPM¶
Windows users who already have ActiveState’s ActivePython distribution installed may find Fabric is best installed with its package manager, pypm. Below is example output from an installation of Fabric 0.9.0 via pypm:
C:\> pypm install fabric Ready to perform these actions: The following packages will be installed: fabric-0.9.0 pycrypto-2.0.1 Get: [pypm.activestate.com] fabric 0.9.0-1 Get: [pypm.activestate.com] pycrypto 2.0.1-1 Installing fabric-0.9.0 Fixing script C:\Users\<username>\AppData\Roaming\Python\Scripts\fab-script.py Installing pycrypto-2.0.1