# pyinfra — Automate Infrastructure with Python

> pyinfra turns Python code into shell commands and runs them on your servers. It supports ad-hoc commands, declarative infrastructure operations, and scales from one server to thousands via SSH, Docker containers, or local execution.

## Install

Save in your project root:

# pyinfra — Automate Infrastructure with Python

## Quick Use
```bash
pip install pyinfra

# Run an ad-hoc command on remote hosts
pyinfra my-server.com exec -- uptime

# Deploy with a Python file
pyinfra my-server.com deploy.py
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-0f62d8ba
Author: AI Open Source