pyinfra Documentation

Connectors in pyinfra allow integration with external tools and fall into three functional categories:

1. Command Execution: Implement how commands are executed on a target (e.g., @ssh, @local).
2. Inventory Generation: Generate inventory hosts and data (e.g., @terraform, @vagrant).
3. Hybrid: Perform both command execution and inventory generation (e.g., @docker, @podman).

pyinfra follows semantic versioning (semver) rules to provide compatibility guarantees:

• Major versions: Contain breaking changes. Warnings for these changes will appear in the latest previous major version.
• Minor versions: Introduce new operations, new APIs, and new global arguments. They may also include deprecation warnings.
• Patch versions: Include bug fixes, documentation updates, and new arguments for existing operations.

pyinfra operations fall into two categories:

• Declarative: Describes an end state (e.g., apt.packages, files.file, server.user). pyinfra checks the current state of the host first and only executes commands if the host does not match the target state. Re-running a deploy where nothing has drifted results in a no-op.
• Imperative: Tells pyinfra to run a specific command unconditionally (e.g., server.shell, server.script, python.call). These always execute.

Use declarative operations for most tasks to ensure idempotency.

Pyinfra allows running shell commands or specific operation modules directly from the CLI without a deployment script.

Shell Commands: Use exec -- to pass commands. Everything after the -- is passed directly to the target host. This is useful for real-time debugging, such as streaming logs.

Built-in Operations: You can call operation modules (e.g., apt.packages, init.service) directly by passing their arguments as CLI arguments.

If you use uv, you can install pyinfra either as a standalone tool or as a dependency within a specific project.

To install it as a global tool:

uv tool install pyinfra

To add it to your current project's dependencies:

uv add pyinfra

An inventory file is a Python file containing groups of hosts defined as list or tuple. Group names cannot start with an underscore (_).

When you run pyinfra inventory.py OPERATIONS..., pyinfra automatically creates:

• An all group containing every host.
• A group named after the filename (e.g., hosts in inventories/production.py belong to the production group).

Note: Files in the inventories/ directory are not automatically joined; they are a convention for organizing multiple related inventories.

app_servers = [
    "app-1.net",
    "app-2.net"
]

db_servers = (["db-1.net", "db-2.net", "db-3.net"], {})

When installing on BSD, you must set specific environment variables to prevent gevent from building embedded versions of certain libraries. You must have c-ares, libev, and libuv installed on your system.

Example using uv:

env C_INCLUDE_PATH='/usr/local/include/' \
    GEVENTSETUP_EMBED_CARES=0 \
    GEVENTSETUP_EMBED_LIBEV=0 \
    GEVENTSETUP_EMBED_LIBUV=0 \
    uv tool install pyinfra

To make pyinfra aware of your custom connector, add an entry point to your project's pyproject.toml file using the pyinfra.connectors group.

[project.entry-points.'pyinfra.connectors']
# Key = Entry point name
# Value = module_path:class_name
custom = 'pyinfra_custom_connector.connector:LoggingConnector'

To use pyinfra as a library rather than a CLI tool, follow this three-step workflow:

1. Initialize State: Create an Inventory (containing Host objects and data), a Config (for global flags), and a State object that combines them.
2. Define Operations: Use pyinfra.api.operation.add_op or pyinfra.api.add_deploy to define the tasks to be performed.
3. Execute: Run the defined operations using pyinfra.api.operations.run_ops.

When upgrading from version 1.x to 2.x, note the following changes:

1. Python Version Requirements: Python 2.7 and Python 3.5 support have been dropped. Python 3.6 is the minimum required version.
2. Working Directory: The "deploy directory" concept has been removed. pyinfra now executes from the current working directory. To set a specific working directory before execution, use the new --chdir CLI flag.

Before reporting a bug, please follow these steps to ensure it is a new and valid issue:

1. Check Compatibility: Scan the compatibility page to see if your environment or issue is already documented.
2. Search Existing Issues: Check the issue list to see if the problem has already been reported.
3. Submit Report: If the issue is new, submit a new bug report on GitHub.