Install & Compatibility
Where this runs
tested against v1.14.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.269s · 41.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.8s · import 0.242s · 42MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
fabric --version
Debug
Known issues
breakingFabric3 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.fixMigrate 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).
affects: All Fabric3 versions
deprecatedThe 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.fixTransition 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.
affects: All Fabric3 versions
gotchaFabric 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.fixWhen 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.
affects: All Fabric3 versions
gotchaThe `fabric.utils.RingBuffer` utility was removed in Fabric 1.x and should not be used. It was commonly replaced by `collections.deque`.fixReplace `fabric.utils.RingBuffer` with `collections.deque` from Python's standard library.
affects: Fabric3 1.14.post1 and later (inherited from Fabric 1.x changes)
Errors
Common errors & fixes
Command 'fab' not found
Fabric3's command-line tool 'fab' is not in your system's PATH, or Fabric3 was not installed correctly for your active Python environment.
fixEnsure 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'
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.
fixIf 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)
This often occurs when remote output or file content contains non-ASCII characters and the terminal or Python environment defaults to an 'ascii' encoding.
fixEnsure 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.
Upgrade
Version history
1.14.post1latest on PyPI · released Feb 11, 2018
Audit
Dependencies
paramikorequiredSSH protocol implementation; requires >=1.17.0 for Python 3 compatibility.
sixrequiredCompatibility layer for Python 2 and 3.