Fabric3

1.14.post1 · deprecated · verified Thu Apr 16

Fabric3 is a Python library and command-line tool designed for remote execution and deployment over SSH, forked from the original Fabric 1.x to provide compatibility with Python 3.4+. While it achieved Python 3 support, the official Fabric project (versions 2.x and above, and eventually 1.15.0) subsequently gained Python 3 compatibility and a redesigned API, rendering Fabric3 obsolete. It is now considered an unauthorized and deprecated fork.

Common errors

```
Command 'fab' not found
```
cause Fabric3's command-line tool 'fab' is not in your system's PATH, or Fabric3 was not installed correctly for your active Python environment.

fix Ensure Fabric3 is installed for your current Python interpreter (`pip show fabric3`). Verify that the Python Scripts directory (e.g., ~/.local/bin on Linux, or C:\Python\Scripts on Windows) is included in your system's PATH. If using virtual environments, activate the environment before running `fab`.
```
ImportError: No module named 'fabric.api'
```
cause Fabric3 is either not installed, or you are trying to import `fabric.api` in an environment where the official `fabric` library (2.x+) is installed, which changed its import paths.

fix If you intend to use Fabric3, ensure it's installed (`pip install fabric3`). If you are migrating to the official Fabric 2.x+, the main import is `from fabric import Connection, task` and `fabric.api` no longer exists.
```
UnicodeDecodeError: 'ascii' codec can't decode byte 0x__ in position __: ordinal not in range(128)
```
cause This often occurs when remote output or file content contains non-ASCII characters and the terminal or Python environment defaults to an 'ascii' encoding.

fix Ensure your local and remote environments are configured to use UTF-8. For example, set `LANG=en_US.UTF-8` and `LC_ALL=en_US.UTF-8` in your shell environments. Fabric3 (and Fabric 1.15.0) addressed some `UnicodeDecodeError` issues, but environment misconfiguration can still cause problems.

Warnings

breaking Fabric3 is an unauthorized and deprecated fork of Fabric 1.x. The official Fabric library (versions 2.x and above) now natively supports Python 3 and has a significantly different, more modern API. Continued use of Fabric3 is strongly discouraged.
Fix: Migrate your codebase to the official Fabric library (pip install fabric). Be aware that Fabric 2.x+ introduces breaking API changes (e.g., uses Connection objects instead of global 'env' state).
deprecated The primary maintainers of the original Fabric project explicitly state that they do not control the `fabric3` PyPI entry and there will be no official `fabric3` or `fabric4` releases. The 1.x branch of mainline Fabric itself gained Python 3 support in version 1.15.0.
Fix: Transition to the official `fabric` package. For co-existence with Fabric 1.x, the official `fabric2` PyPI package provides Fabric 2.x+ under a distinct name. Users are encouraged to fully migrate to Fabric 2.x+ to avoid future compatibility issues.
gotcha Fabric 1.x (and thus Fabric3) relies heavily on a global `env` object for configuration, which can lead to issues in concurrent or complex environments. Fabric 2.x+ uses explicit `Connection` objects.
Fix: When migrating to Fabric 2.x+, refactor code to use `Connection` instances for managing host-specific configurations and operations. This provides better isolation and thread-safety.
gotcha The `fabric.utils.RingBuffer` utility was removed in Fabric 1.x and should not be used. It was commonly replaced by `collections.deque`.
Fix: Replace `fabric.utils.RingBuffer` with `collections.deque` from Python's standard library.

Install

pip install fabric3 Install Fabric3

Imports

run
```
from fabric.api import run
```
Primary function for executing remote shell commands.
env
```
from fabric.api import env
```
Global dictionary for Fabric's environment settings (Fabric 1.x style).
local
```
from fabric.api import local
```
Function for executing local shell commands.
cd
```
from fabric.api import cd
```
Context manager for changing remote directory.
sudo
```
from fabric.api import sudo
```
Function for executing remote commands with superuser privileges.
put
```
from fabric.api import put
```
Function for uploading files to remote hosts.
get
```
from fabric.api import get
```
Function for downloading files from remote hosts.

Quickstart

Create a file named `fabfile.py`. Define functions which will be executed as tasks. The `env` object is used for global configuration such as hosts and credentials. Tasks are executed from the command line using the `fab` command, e.g., `fab deploy`.

# fabfile.py
from fabric.api import run, env, sudo, put

# Configure hosts (replace with actual SSH connection details)
env.hosts = ['user@your_remote_host_ip']
env.password = 'your_ssh_password' # Or use SSH agent/key
env.warn_only = True # Don't abort on non-zero exit codes

def deploy():
    print(f"Deploying to {env.host_string}...")
    # Example: Update package lists and install nginx
    sudo('apt-get update && apt-get install -y nginx')
    run('service nginx start')
    print("Nginx installed and started.")

    # Example: Upload a local file
    local_path = '/tmp/test_file.txt'
    remote_path = '/tmp/remote_test.txt'
    with open(local_path, 'w') as f:
        f.write('Hello from Fabric3!')
    put(local_path, remote_path)
    run(f'cat {remote_path}')
    print("File uploaded and content verified.")

# To run this from your terminal:
# fab deploy

view raw JSON →