Installation¶

Prerequisites¶

Python Version Requirements¶

• Python 3.10 or later is required
• pyinfra 3.5.1+ supports Python 3.10, 3.11, 3.12 and 3.13
• You can check your Python version with:

python --version

System Requirements¶

• A Unix-like operating system (Linux, macOS) or Windows
• Shell access to target systems
• For Windows users: Administrator privileges for installation
• For development: A C++ compiler may be required for some Python packages

Installation Method¶

Using uv (Recommended)¶

First install uv if you haven't already.

Now you can install pyinfra as a tool, or add it to your project's dependencies.

Installing pyinfra as a tool¶

# install pyinfra
uv tool install pyinfra

# verify installation
pyinfra --version

Adding pyinfra to your project dependencies¶

# add pyinfra to your project dependencies
uv add pyinfra

# verify installation
uv run pyinfra --version

Using pipx¶

First install pipx if you haven't already.

Install pyinfra via pipx¶

pipx install pyinfra

Verify pipx Installation¶

pyinfra --version

Using pip¶

Create a Virtual Environment (Best Practice)¶

# Create a virtual environment
python -m venv env

# Activate the virtual environment
# On macOS/Linux
source env/bin/activate
# On Windows
env\Scripts\activate

Install pyinfra via pip¶

pip install pyinfra

Verify pip Installation¶

pyinfra --version

Platform-Specific Instructions¶

BSD Installation¶

Regardless of your installation method, you will need to preface commands with some environmental variables that prevent gevent (a dependency) from building embedded versions of some libraries.

```sh
# Example for installing pyinfra as a tool under a BSD
env C_INCLUDE_PATH='/usr/local/include/' \
    GEVENTSETUP_EMBED_CARES=0 \
    GEVENTSETUP_EMBED_LIBEV=0 \
    GEVENTSETUP_EMBED_LIBUV=0 \
    uv tool install pyinfra
```

Note that you'll still need c-ares, libev and libuv in your system.

Windows Installation¶

Install Python¶

• Download from Python's official website
• Run installer as Administrator
• Check "Add Python to PATH" during installation

Optional: Install C++ Compiler¶

• Download Visual Studio Community Edition
• Select "Desktop development with C++" workload
• Required components:
• MSVC v142...
• Windows 10 SDK...
• C++ CMake tools for Windows
• C++ ATL for latest...
• C++/CLI support for v142...
• C++ Modules for v142...

Install pyinfra on Windows¶

python -m venv env
env\Scripts\activate
pip install pyinfra

Best Practices¶

Do's¶

• ✅ Use virtual environments for isolation
• ✅ Keep pyinfra and dependencies up-to-date
• ✅ Use the latest Python version supported
• ✅ Install as a regular user (not root/sudo)

Don'ts¶

• ❌ Avoid system-wide installation
• ❌ Don't mix pyinfra with other projects in the same virtual environment
• ❌ Don't use unsupported package managers (poetry, pip-tools)

Troubleshooting¶

Common Issues¶

Permission Errors¶

• Ensure you're not using sudo for installation
• Check virtual environment permissions
• Verify Python installation directory permissions

Python Version Issues¶

• Verify Python version meets requirements
• Consider using pyenv or similar version manager

Virtual Environment Issues¶

• Ensure virtual environment is properly activated
• Check PATH environment variable
• Verify Python interpreter location

Updating pyinfra¶

To update to the latest version:

pip install --upgrade pyinfra