What it is

pyinfra is a Python-based infrastructure automation tool that turns Python code into shell commands and runs those commands on remote servers. It lives in the configuration management and cloud infrastructure management space, and it targets SSH servers, the local machine, and Docker containers through a connector system. The project is written in Python, licensed under MIT, and has been developed for roughly twelve years. Its own description frames it as "ansible but Python instead of YAML."

The concrete problem it solves is the gap between ad-hoc shell work and heavyweight declarative configuration files. Instead of writing YAML playbooks, a user writes ordinary Python, using packaged operations that describe desired state rather than raw commands. Those operations are idempotent, which makes diffs and dry runs possible before anything changes on a host. Because execution is agentless, nothing has to be installed on the target beyond shell access, and the same inventory can address one machine or thousands.

Key capabilities

• Idempotent operations that support diffs and dry runs before changes are applied.
• Agentless execution against anything reachable over shell access.
• Parallel execution that scales from a single host to thousands with predictable performance.
• Realtime stdin, stdout, and stderr streaming for debugging, exposed through the -vvv flag.
• Extensibility through the entire Python package ecosystem.
• Connectors for Docker, Terraform, Vagrant, and other targets, alongside SSH and local execution.
• A CLI that can run either ad-hoc shell commands or saved operation files against a named inventory.

Who uses it and how

• Running ad-hoc commands over SSH, for example pyinfra my-server.net exec -- echo "hello world".
• Applying package state directly from the command line, such as installing iftop on a Docker target with pyinfra @docker/ubuntu apt.packages iftop update=true _sudo=true.
• Writing reusable deployment files in Python, where operations such as apt.packages are imported and called with a name, package list, and sudo flag.
• Defining target hosts in an inventory file, such as one listing both @docker/ubuntu and a test server, then running an inventory and a deploy file together.
• Targeting the local machine or a container for testing a deployment before it reaches real servers.

Getting started

Install with uv tool install pyinfra, then execute commands over SSH or against connectors such as @docker/ubuntu and @local. Operations can be run inline from the CLI or saved into Python files and executed against an inventory.

When to use it — and when not to

It is a reasonable replacement for paid configuration management products when the team already writes Python and wants to avoid a YAML domain-specific language. A self-hoster operates the control machine and its Python environment rather than a server component, since execution is agentless. The main weakness visible in the facts is the open issue count of 160, which suggests a project with a live backlog to review before adopting it for critical infrastructure.

uv tool install pyinfra

pyinfra my-server.net exec -- echo "hello world"

pyinfra @docker/ubuntu exec -- echo "Hello world"
pyinfra @local exec -- echo "Hello world"

# Install iftop apt package if not present
pyinfra @docker/ubuntu apt.packages iftop update=true _sudo=true

from pyinfra.operations import apt

apt.packages(
    name="Ensure iftop is installed",
    packages=['iftop'],
    update=True,
    _sudo=True,
)

targets = ["@docker/ubuntu", "my-test-server.net"]

pyinfra inventory.py deploy.py