Changes in version 1.0

This page lists all changes made to Fabric in its 1.0.0 release.


  • #7: run/sudo now allow full interactivity with the remote end. You can interact with remote prompts and similar interfaces, making certain tasks much easier, and freeing you from the need to find noninteractive solutions if you don’t want to. See Interaction with remote programs for more on these changes.
  • put and get received many updates, including but not limited to: recursion, globbing, inline sudo capability, and increased control over local file paths. See the individual ticket line-items below for details. Erich Heine (sophacles on IRC) played a large part in implementing and/or collecting these changes and deserves much of the credit.
  • Added functionality for loading fabfiles which are Python packages (directories) instead of just modules (single files). This allows for easier organization of nontrivial fabfiles and paves the way for task namespacing in the near future. See Fabfile discovery for details.
  • #185: Mostly of interest to those contributing to Fabric itself, Fabric now leverages Paramiko to provide a stub SSH and SFTP server for use during runs of our test suite. This makes quick, configurable full-stack testing of Fabric (and, to an extent, user fabfiles) possible.

Backwards-incompatible changes

The below changes are backwards incompatible and have the potential to break your 0.9.x based fabfiles!

  • contains and append previously had the filename argument in the second position, whereas all other functions in the contrib.files module had filename as the first argument. These two functions have been brought in line with the rest of the module.
  • sed now escapes single-quotes and parentheses in addition to forward slashes, in its before and after kwargs. Related to, but not entirely contained within, #159.
  • The user and pty kwargs in sudo‘s signature have had their order swapped around to more closely match run.
  • As part of the changes made in #7, run and sudo have had the default value of their pty kwargs changed from False to True. This, plus the addition of the combine_stderr kwarg/env var, may result in significant behavioral changes in remote programs which operate differently when attached to a tty.
  • #61: put and get now honor the remote current-working-directory changes applied by cd. Previously they would always treat relative remote paths as being relative to the remote home directory.
  • #79: get now allows increased control over local filenames when downloading single or multiple files. This is backwards incompatible because the default path/filename for downloaded files has changed. Thanks to Juha Mustonen, Erich Heine and Max Arnold for brainstorming solutions.
  • #88: local has changed the default value of its capture kwarg, from True to False. This was changed in order to be more intuitive, at the cost of no longer defaulting to the same rich return value as in run/sudo (which is still available by specifying capture=True.)
  • #121: put will no longer automatically attempt to mirror local file modes. Instead, you’ll need to specify mirror_local_mode=True to get this behavior. Thanks to Paul Smith for a patch covering part of this change.
  • #172: append has changed the default value of its partial kwarg from True to False in order to be safer/more intuitive.
  • #221: runs_once now memoizes the wrapped task’s return value and returns that value on subsequent invocations, instead of returning None. Thanks to Jacob Kaplan-Moss and Travis Swicegood for catch + patch.

Feature additions

  • Prerelease versions of Fabric (starting with the 1.0 prereleases) will now print the Git SHA1 hash of the current checkout, if the user is working off of a Git clone of the Fabric source code repository.
  • Added path context manager for modifying commands’ effective $PATH.
  • Added convenience .succeeded attribute to the return values of run/sudo/local which is simply the opposite of the .failed attribute. (This addition has also been backported to Fabric’s 0.9 series.)
  • Refactored SSH disconnection code out of the main fab loop into disconnect_all, allowing library users to avoid problems with non-fabfile Python scripts hanging after execution finishes.
  • #2: Added use_sudo kwarg to put to allow uploading of files to privileged locations. Thanks to Erich Heine and IRC user npmap for suggestions and patches.
  • #23: Added prefix context manager for easier management of persistent state across commands.
  • #27: Added environment variable (always_use_pty) and command-line flag (--no-pty) for global control over the run/sudo pty argument.
  • #28: Allow shell-style globbing in get. Thanks to Erich Heine and Max Arnold.
  • #55: run, sudo and local now provide access to their standard error (stderr) as an attribute on the return value, alongside e.g. .failed.
  • #148: local now returns the same “rich” string object as run/sudo do, so that it is a string containing the command’s stdout (if capture=True) or the empty string (if capture=False) which exposes the .failed and .return_code attributes, and so forth.
  • #151: Added a puts utility function, which allows greater control over fabfile-generated (as opposed to Fabric-generated) output. Also added fastprint, an alias to puts allowing for convenient unbuffered, non-newline-terminated printing.
  • #192: Added per-user/host password cache to assist in multi-connection scenarios.
  • #193: When requesting a remote pseudo-terminal, use the invoking terminal’s dimensions instead of going with the default.
  • #217: get/put now accept file-like objects as well as local file paths for their local_path arguments.
  • #245: Added the lcd context manager for controlling local‘s current working directory and put/get‘s local working directories.
  • #274: put/get now have return values which may be iterated over to access the paths of files uploaded remotely or downloaded locally, respectively. These return values also allow access to .failed and .succeeded attributes, just like run and friends. (In this case, .failed is actually a list itself containing any paths which failed to transfer, which naturally acts as a boolean as well.)


  • N/A

Documentation updates

  • API, tutorial and usage docs updated with the above new features.
  • README now makes the Python 2.5+ requirement up front and explicit; some folks were still assuming it would run on Python 2.4.
  • Added a link to Python’s documentation for string interpolation in upload_template‘s docstring.