Skip to main content
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:
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
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).
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

uv is the fastest Python package installer. Install pyinfra as a tool: 
uv tool install pyinfra
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 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
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:
1

Clone the repository

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

Install with uv

# Install development dependencies
uv sync --all-extras

# Install in editable mode
uv pip install -e .
3

Or install with pip

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

# Install in editable mode
pip install -e .
4

Verify installation

pyinfra --version
  • 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:
1

Check version

pyinfra --version
You should see output like:
pyinfra 3.6.1
2

Test help command

pyinfra --help
This shows all available commands and options.
3

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 "[email protected]"
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
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
Restart your shell or source the config file to enable completion.

​
Troubleshooting

​
Common Issues

Problem: The pyinfra command isn’t in your PATH.Solutions:
  1. If using pipx: Run pipx ensurepath and restart your shell
  2. If using pip —user: Add ~/.local/bin to your PATH: 
    export PATH="$HOME/.local/bin:$PATH"
  3. If using virtual environment: Make sure it’s activated: 
    source venv/bin/activate
Problem: Dependencies weren’t installed correctly.Solution: Reinstall with dependencies:
pip install --force-reinstall pyinfra
Problem: System Python is too old (< 3.10).Solutions:
  1. Install a newer Python version: 
    # macOS
brew install [email protected]

# Ubuntu
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12
  2. Use pyenv to manage Python versions: 
    curl https://pyenv.run | bash
pyenv install 3.12
pyenv global 3.12
Problem: Trying to install globally without sudo.Solutions:
  1. Use pipx or uv (recommended)
  2. Use pip with —user flag: 
    pip install --user pyinfra
  3. Use a virtual environment
Problem: Corporate proxy or firewall blocking PyPI.Solutions:
  1. Configure pip to use your proxy: 
    pip install --proxy=http://proxy.example.com:8080 pyinfra
  2. Use your organization’s PyPI mirror: 
    pip install --index-url=https://pypi.example.com/simple pyinfra
Problem: Can’t connect to Docker daemon.Solutions:
  1. Ensure Docker is running: 
    docker ps
  2. Add your user to the docker group: 
    sudo usermod -aG docker $USER
newgrp docker
  3. 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
Check what’s new in the changelog.

​
Development Installation

For contributing to pyinfra or developing custom operations:
1

Clone and setup

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

Install with dev dependencies

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

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

Install pre-commit hooks

pre-commit install
4

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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us