Fabric

About

Fabric is a Python (2.5 or higher) library and command-line tool for streamlining the use of SSH for application deployment or systems administration tasks.

It provides a basic suite of operations for executing local or remote shell commands (normally or via sudo) and uploading/downloading files, as well as auxiliary functionality such as prompting the running user for input, or aborting execution.

Typical use involves creating a Python module containing one or more functions, then executing them via the fab command-line tool. Below is a small but complete “fabfile” containing a single task:

from fabric.api import run

def host_type():
    run('uname -s')

Once a task is defined, it may be run on one or more servers, like so:

$ fab -H localhost,linuxbox host_type
[localhost] run: uname -s
[localhost] out: Darwin
[linuxbox] run: uname -s
[linuxbox] out: Linux

Done.
Disconnecting from localhost... done.
Disconnecting from linuxbox... done.

In addition to use via the fab tool, Fabric’s components may be imported into other Python code, providing a Pythonic interface to the SSH protocol suite at a higher level than that provided by e.g. the ssh library (which Fabric itself uses.)

Installation

Stable releases of Fabric are best installed via pip or easy_install; or you may download TGZ or ZIP source archives from a couple of official locations. Detailed instructions and links may be found on the Installation page.

We recommend using the latest stable version of Fabric; releases are made often to prevent any large gaps in functionality between the latest stable release and the development version.

However, if you want to live on the edge, you can pull down the source code from our Git repository, or fork us on Github. The Installation page has details for how to access the source code.

Development

Any hackers interested in improving Fabric (or even users interested in how Fabric is put together or released) please see the Development page. It contains comprehensive info on contributing, repository layout, our release strategy, and more.

Documentation

Please note that all documentation is currently written with Python 2.5 users in mind, but with an eye for eventual Python 3.x compatibility. This leads to the following patterns that may throw off readers used to Python 2.4 or who have already upgraded to Python 2.6/2.7:

• from __future__ import with_statement: a “future import” required to use the with statement in Python 2.5 – a feature you’ll be using frequently. Python 2.6+ users don’t need to do this.
• <true_value> if <expression> else <false_value>: Python’s relatively new ternary statement, available in 2.5 and newer. Python 2.4 and older used to fake this with <expression> and <true_value> or <false_value> (which isn’t quite the same thing and has some logical loopholes.)
• print(<expression>) instead of print <expression>: We use the print statement’s optional parentheses where possible, in order to be more compatible with Python 3.x (in which print becomes a function.)

Tutorial

For new users, and/or for an overview of Fabric’s basic functionality, please see the Overview and Tutorial. The rest of the documentation will assume you’re at least passingly familiar with the material contained within.

Usage documentation

The following list contains all major sections of Fabric’s prose (non-API) documentation, which expands upon the concepts outlined in the Overview and Tutorial and also covers advanced topics.

• The environment dictionary, env
  • Environment as configuration
  • Environment as shared state
  • Other considerations
  • Full list of env vars
• Execution model
  • Execution strategy
  • Defining tasks
  • Defining host lists
  • Intelligently executing tasks with execute
  • Failure handling
  • Connections
  • Password management
  • Leveraging native SSH config files
• fab options and arguments
  • Basic use
  • Arbitrary remote shell commands
  • Command-line options
  • Per-task arguments
  • Settings files
• Fabfile construction and use
  • Fabfile discovery
  • Importing Fabric
  • Defining tasks and importing callables
• Interaction with remote programs
  • Combining stdout and stderr
  • Pseudo-terminals
  • Combining the two
• Library Use
  • Connections
  • Disconnecting
  • Final note
• Managing output
  • Output levels
  • Hiding and/or showing output levels
• Parallel execution
  • What it does
  • How to use it
  • Bubble size
  • Linewise vs bytewise output
• SSH behavior
  • Unknown hosts
  • Known hosts with changed keys
• Defining tasks
  • New-style tasks
  • Classic tasks

FAQ

Some frequently encountered questions, coupled with answers/solutions/excuses, may be found on the Frequently Asked Questions (FAQ) page.

API documentation

Fabric maintains two sets of API documentation, autogenerated from the source code’s docstrings (which are typically very thorough.)

Core API

The core API is loosely defined as those functions, classes and methods which form the basic building blocks of Fabric (such as run and sudo) upon which everything else (the below “contrib” section, and user fabfiles) builds.

• Color output functions
• Context Managers
• Decorators
• Network
• Operations
• Tasks
• Utils

Contrib API

Fabric’s contrib package contains commonly useful tools (often merged in from user fabfiles) for tasks such as user I/O, modifying remote files, and so forth. While the core API is likely to remain small and relatively unchanged over time, this contrib section will grow and evolve (while trying to remain backwards-compatible) as more use-cases are solved and added.

• Console Output Utilities
• Django Integration
• File and Directory Management
• Project Tools

Changelog

Please see the changelog.

Roadmap

Please see the roadmap.

Getting help

If you’ve scoured the prose and API documentation and still can’t find an answer to your question, below are various support resources that should help. We do request that you do at least skim the documentation before posting tickets or mailing list questions, however!

Mailing list

The best way to get help with using Fabric is via the fab-user mailing list (currently hosted at nongnu.org.) The Fabric developers do their best to reply promptly, and the list contains an active community of other Fabric users and contributors as well.

Twitter

Fabric has an official Twitter account, @pyfabric, which is used for announcements and occasional related news tidbits (e.g. “Hey, check out this neat article on Fabric!”).

Bugs/ticket tracker

To file new bugs or search existing ones, you may visit Fabric’s Github Issues page. This does require a (free, easy to set up) Github account.

IRC

We maintain a semi-official IRC channel at #fabric on Freenode (irc://irc.freenode.net) where the developers and other users may be found. As always with IRC, we can’t promise immediate responses, but some folks keep logs of the channel and will try to get back to you when they can.

Wiki

There is an official Fabric MoinMoin wiki reachable at wiki.fabfile.org, although as of this writing its usage patterns are still being worked out. Like the ticket tracker, spam has forced us to put anti-spam measures up: the wiki has a simple, easy captcha in place on the edit form.