Installation

This guide covers all the ways to install pyinfra and get your development environment ready.

System Requirements

Before installing pyinfra, ensure your system meets these requirements:

Python Version

pyinfra requires Python 3.10 or higher. Supported versions:

Python 3.10
Python 3.11
Python 3.12
Python 3.13

Check your Python version:

python --version

Operating System

pyinfra works on:

Linux (all major distributions)
macOS (Intel and Apple Silicon)
Windows (via WSL2 recommended)

The tool itself is OS-independent, but targets POSIX-compatible systems (Linux/BSD/macOS).

Dependencies

pyinfra will automatically install these Python dependencies:

gevent>=1.5 - Concurrent execution engine
paramiko>=2.7,<4 - SSH connectivity
click>2 - CLI framework
jinja2>3,<4 - Template rendering
python-dateutil>2,<3 - Date handling
distro>=1.6,<2 - OS detection
packaging>=16.1 - Version parsing
pydantic>=2.11,<3 - Data validation

Installation Methods

Using uv (Recommended)

uv is the fastest Python package installer. Install pyinfra as a tool:

uv tool install pyinfra

pyinfra --version

Why uv? It’s significantly faster than pip, has better dependency resolution, and manages isolated tool environments automatically.

Using pipx

pipx installs Python CLI tools in isolated environments:

# On macOS
brew install pipx
pipx ensurepath

# On Ubuntu/Debian
sudo apt install pipx
pipx ensurepath

# On other systems
python -m pip install --user pipx
python -m pipx ensurepath

pipx install pyinfra

pyinfra --version

pipx is great if you want pyinfra available globally but isolated from other Python projects.

Using pip

Install with pip for traditional Python package management:

pip install pyinfra

pip install --user pyinfra

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install pyinfra

pyinfra --version

Installing with pip globally can cause conflicts with system packages. Consider using a virtual environment or pipx instead.

From Source

Install the latest development version directly from GitHub:

Clone the repository

git clone https://github.com/pyinfra-dev/pyinfra.git
cd pyinfra

Install with uv

# Install development dependencies
uv sync --all-extras

# Install in editable mode
uv pip install -e .

Or install with pip

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate

# Install in editable mode
pip install -e .

Verify installation

pyinfra --version

Why install from source?

Access to unreleased features and bug fixes
Contributing to pyinfra development
Testing patches before official release
Custom modifications for your use case

Verifying Installation

After installation, verify everything works correctly:

Check version

pyinfra --version

You should see output like:

pyinfra 3.6.1

Test help command

pyinfra --help

This shows all available commands and options.

Run a simple test

Test local execution:

pyinfra @local exec -- echo "pyinfra works!"

You should see:

--> Loading inventory...
--> Connecting to hosts...
    [@local] Connected

--> Executing...
    [@local] echo "pyinfra works!"
    [@local] pyinfra works!

--> Results:
    Commands: 1
    Success: 1

If all three steps work, pyinfra is installed correctly!

Additional Setup

SSH Configuration

For SSH connectivity, ensure you have proper SSH setup:

ssh-keygen -t ed25519 -C "your-email@example.com"

ssh-copy-id user@your-server.com

ssh user@your-server.com

pyinfra respects your ~/.ssh/config file. Configure connection settings there for easy access:

~/.ssh/config

Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Then use: pyinfra myserver deploy.py

Docker Setup (Optional)

To use the Docker connector, install Docker:

brew install --cask docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

docker --version

Test the Docker connector:

pyinfra @docker/ubuntu exec -- echo "Hello from Docker!"

Enabling Shell Completion

pyinfra supports shell completion for bash, zsh, and fish:

pyinfra --install-completion bash

pyinfra --install-completion zsh

pyinfra --install-completion fish

Restart your shell or source the config file to enable completion.

Troubleshooting

Common Issues

'pyinfra' command not found

Problem: The pyinfra command isn’t in your PATH.Solutions:

If using pipx: Run pipx ensurepath and restart your shell
If using pip —user: Add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"
If using virtual environment: Make sure it’s activated:
source venv/bin/activate

ImportError: No module named 'gevent'

Problem: Dependencies weren’t installed correctly.Solution: Reinstall with dependencies:

pip install --force-reinstall pyinfra

Python version errors

Problem: System Python is too old (< 3.10).Solutions:

Install a newer Python version:

# macOS
brew install python@3.12

# Ubuntu
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12

Use pyenv to manage Python versions:

curl https://pyenv.run | bash
pyenv install 3.12
pyenv global 3.12

Permission denied errors

Problem: Trying to install globally without sudo.Solutions:

Use pipx or uv (recommended)
Use pip with —user flag:
pip install --user pyinfra
Use a virtual environment

SSL certificate errors

Problem: Corporate proxy or firewall blocking PyPI.Solutions:

Configure pip to use your proxy:

pip install --proxy=http://proxy.example.com:8080 pyinfra

Use your organization’s PyPI mirror:

pip install --index-url=https://pypi.example.com/simple pyinfra

Docker connector not working

Problem: Can’t connect to Docker daemon.Solutions:

Ensure Docker is running:
docker ps

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Check Docker socket permissions:
ls -l /var/run/docker.sock

Upgrading pyinfra

Keep pyinfra up to date to get the latest features and bug fixes:

uv tool upgrade pyinfra

pipx upgrade pyinfra

pip install --upgrade pyinfra

Check what’s new in the changelog.

Development Installation

For contributing to pyinfra or developing custom operations:

Clone and setup

git clone https://github.com/pyinfra-dev/pyinfra.git
cd pyinfra

Install with dev dependencies

# Using uv (recommended)
uv sync --all-extras

# Or using pip
pip install -e ".[dev]"

Install pre-commit hooks

pre-commit install

Run tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=pyinfra

# Run linting
ruff check .
mypy src/pyinfra src/pyinfra_cli

Development dependencies include:

pytest and pytest-cov for testing
ruff for linting
mypy for type checking
ipython and ipdb for debugging

Uninstalling pyinfra

If you need to remove pyinfra:

uv tool uninstall pyinfra

pipx uninstall pyinfra

pip uninstall pyinfra

Next Steps

Now that pyinfra is installed:

Quickstart Guide

Run your first deployment

Core Concepts

Understand how pyinfra works

CLI Reference

Master the command line interface

Operations

Explore available operations

Getting Help

If you encounter issues not covered here:

GitHub Issues

Report bugs and installation problems

GitHub Discussions

Ask questions and get community support

Matrix Chat

Real-time chat with the community

Contributing Guide

Learn how to contribute to pyinfra

Get Started

Core Concepts

Guides

CLI Reference

Advanced

System Requirements

Installation Methods

Using uv (Recommended)

Using pipx

Using pip

From Source

Verifying Installation

Additional Setup

SSH Configuration

Docker Setup (Optional)

Enabling Shell Completion

Troubleshooting

Common Issues

Upgrading pyinfra

Development Installation

Uninstalling pyinfra

Next Steps

Quickstart Guide

Core Concepts

CLI Reference

Operations

Getting Help

GitHub Issues

GitHub Discussions

Matrix Chat

Contributing Guide

​System Requirements

​Installation Methods

​Using uv (Recommended)

​Using pipx

​Using pip

​From Source

​Verifying Installation

​Additional Setup

​SSH Configuration

​Docker Setup (Optional)

​Enabling Shell Completion

​Troubleshooting

​Common Issues

​Upgrading pyinfra

​Development Installation

​Uninstalling pyinfra

​Next Steps

Quickstart Guide

Core Concepts

CLI Reference

Operations

​Getting Help

GitHub Issues

GitHub Discussions

Matrix Chat

Contributing Guide

System Requirements

Installation Methods

Using uv (Recommended)

Using pipx

Using pip

From Source

Verifying Installation

Additional Setup

SSH Configuration

Docker Setup (Optional)

Enabling Shell Completion

Troubleshooting

Common Issues

Upgrading pyinfra

Development Installation

Uninstalling pyinfra

Next Steps

Getting Help