pyinfra — Automate Infrastructure with Python

Introduction

pyinfra is an infrastructure automation tool that uses Python as its configuration language. Instead of YAML or DSL-based playbooks, you write standard Python scripts that describe the desired state of your servers. pyinfra compiles these into shell commands and executes them over SSH, locally, or inside Docker containers. It is agentless and requires no software installed on target machines.

What pyinfra Does

• Executes ad-hoc shell commands across one or many servers in parallel
• Provides declarative operations for packages, files, services, users, and system configuration
• Supports SSH, Docker, local, and custom connector backends
• Generates change diffs showing what will be modified before applying
• Handles facts (system state queries) and conditional logic using plain Python

Architecture Overview

pyinfra works in three stages: inventory resolution, operation compilation, and execution. The inventory defines hosts and groups using Python data structures. Operations are Python functions that describe desired state (e.g., ensure a package is installed). pyinfra collects facts from target hosts, computes the required changes, and executes shell commands through the chosen connector. All operations are idempotent by default.

Self-Hosting & Configuration

• Install with pip install pyinfra on any machine with Python 3.8+
• Define hosts in inventory files or pass them directly on the command line
• Write deploy scripts using built-in operations from pyinfra.operations
• Group hosts and assign data using Python dictionaries and variables
• Use --dry flag to preview changes without applying them

Key Features

• Pure Python configuration with full access to loops, conditionals, and libraries
• Agentless architecture requiring only SSH access to target machines
• Parallel execution across thousands of hosts with configurable concurrency
• Built-in operations covering apt, yum, pip, files, systemd, git, and Docker
• Instant dry-run mode showing exactly what commands will execute

Comparison with Similar Tools

• Ansible — YAML-based with a steeper learning curve for complex logic; pyinfra uses native Python
• SaltStack — Requires a master/minion architecture; pyinfra is agentless and push-based
• Fabric — Imperative command runner; pyinfra adds declarative, idempotent operations
• Chef/Puppet — Agent-based with Ruby DSLs; pyinfra is agentless with Python
• Terraform — Focused on cloud resource provisioning; pyinfra manages server configuration

FAQ

Q: Do I need to install anything on the target servers? A: No. pyinfra is agentless and only requires SSH access and a POSIX shell on the remote hosts.

Q: Can pyinfra replace Ansible? A: For many use cases, yes. pyinfra handles the same configuration management tasks with Python instead of YAML, which simplifies complex logic.

Q: Does pyinfra support Windows targets? A: pyinfra primarily targets Linux and Unix systems. Windows support is limited and experimental.

Q: How does pyinfra handle secrets? A: You can use Python environment variables, vault libraries, or any secret manager since deploy files are standard Python scripts.

Sources

• https://github.com/pyinfra-dev/pyinfra
• https://docs.pyinfra.com/