pyinfra: Python code into shell commands across servers

My notes

Summary

pyinfra is a Python-based infrastructure automation tool that compiles Python code into shell commands and executes them over SSH, Docker, or locally. It positions itself as a faster, agentless alternative to Ansible, Python instead of YAML, with realtime stdin/stdout/stderr output (-vvv) and idempotent operations supporting diffs and dry runs.

Key Insight

• Speed-first design. Claims predictable performance against thousands of hosts in parallel, Ansible’s biggest weakness is exactly this scaling pain.
• No YAML. Operations are plain Python, which means full IDE support, type hints, normal debugging, and access to the whole Python package ecosystem. No more Jinja-in-YAML acrobatics.
• Connectors built-in. Targets aren’t only SSH servers: @docker/<image>, @local, plus Terraform and Vagrant connectors mean you can drive the same operation across very different runtimes without rewriting playbooks.
• Realtime output by default. Live stdin/stdout/stderr with -vvv is concretely better than Ansible’s “wait silently then dump” UX.
• Idempotent + dry-run. Diff before apply, a hard requirement for production, often bolted on awkwardly elsewhere.
• Install via uv. uv tool install pyinfra, fits modern Python tooling, no global pip pollution.
• Two-file pattern. Inventory (inventory.py) lists hosts; deploy file (deploy.py) declares operations. Run together: pyinfra inventory.py deploy.py. Same mental model as Ansible but with Python types.
• Ad-hoc commands work too. pyinfra my-server.net exec -- echo "hello", handy for one-off ops without writing a playbook.