Registry / devops / pyinfra

pyinfra

JSON →
library3.9.2pypypi✓ verified 87d ago

pyinfra is an infrastructure automation tool that transforms Python code into shell commands, executing them on remote servers, local machines, or Docker containers. It offers fast, agentless deployments and scales from single servers to thousands, aiming to be a Python-based alternative to YAML-centric tools like Ansible. It is currently at version 3.7 and maintains an active development and release cadence.

pip install pyinfra
INSTALL
IMPORT
SIG · PYINFRA
P
pyinfra
devopspythonv3.9.2
Install
6.5s avg
Import
1407ms
Disk
74MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.9.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 7.83s
py 3.11
✓ —
✓ 6.65s
py 3.12
✓ —
✓ 5.53s
py 3.13
✓ —
✓ 5.85s
py 3.9
✕ build_error
✕ build_error
74MB installed
● package 74MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

apt.packages
from pyinfra.operations import apt
Operations like `apt.packages`, `files.file`, `server.shell` are imported from the `pyinfra.operations` module.
host
from pyinfra import host
The `host` object provides context about the current target host.
Hostname (fact)
from pyinfra.facts.server import Hostname
Facts are imported from `pyinfra.facts` to gather information about target systems.
deploy (decorator)
from pyinfra.api import deploy
@deploy
As of pyinfra v3, the `deploy` decorator must be called as `@deploy()`.

This quickstart demonstrates how to define a simple pyinfra deploy to install and configure Nginx on a target. Save this code as `deploy.py`. To execute it, you would typically run `pyinfra <inventory> deploy.py` from your terminal. For local testing, use `pyinfra @local deploy.py`. To target a remote server via SSH, use `pyinfra my-server.net deploy.py --ssh-user <your_user>`. The `apt.update` and `apt.packages` operations ensure idempotency, meaning they only make changes if necessary.

import os from pyinfra.operations import apt, files # Define target hosts (using @local for a quick test) # For remote SSH, change to: hosts = ['my-server.net'] # For Docker, change to: hosts = ['@docker/ubuntu:latest'] # Create a dummy inventory file if running with `pyinfra inventory.py deploy.py` # In a real scenario, this would connect to actual hosts. # If running directly, pyinfra will prompt or use @local if no inventory is specified. # deploy.py # Ensure apt packages are updated and Nginx is installed apt.update(name="Update apt repositories", _sudo=True) apt.packages(name="Install Nginx", packages=['nginx'], _sudo=True) # Ensure Nginx service is running and enabled files.file( name="Ensure Nginx config is present", path="/etc/nginx/sites-available/default", contents=""" server { listen 80 default_server; listen [::]:80 default_server; root /var/www/html; index index.html index.htm index.nginx-debian.html; server_name _; location / { try_files $uri $uri/ =404; } } """, _sudo=True ) apt.update( name="Run apt update (idempotent)", _sudo=True ) apt.packages( name="Install Nginx (idempotent)", packages=["nginx"], _sudo=True ) # To make this runnable directly as a Python script for illustration: # This part is typically handled by the `pyinfra` CLI. # We will simulate a direct execution for simplicity, but real use is via `pyinfra <inventory> <deploy>`. # import sys # from pyinfra.api.local import Local # with Local(['@local']) as state: # # In a real deploy.py, the operations would run directly. # # For this quickstart, we just define them as above. # print("Deploy operations defined. Run with: pyinfra @local deploy.py") # print("Or via SSH: pyinfra my-host.net deploy.py") # Example of how to execute from CLI: # Create a file named 'deploy.py' with the above content. # Then run: pyinfra @local deploy.py # Or to a remote host: pyinfra my-server.net deploy.py --ssh-user <your_user> --ssh-password "$PYINFRA_SSH_PASSWORD"
pyinfra --version
Debug
Known issues
breakingThe `_use_sudo_password` argument has been renamed to `_sudo_password` in pyinfra v3.x.
fix
Update all occurrences of `_use_sudo_password` to `_sudo_password`.
affects: 3.0.0+
breakingThe `@deploy` decorator must now be called as a function: `@deploy()` instead of `@deploy` in pyinfra v3.x.
fix
Change `@deploy` to `@deploy()` wherever it is used to define a deploy function.
affects: 3.0.0+
breakingThe `winrm` connector and `windows*` operations/facts have been removed from the core `pyinfra` package in v3.x and moved to the `pyinfra-windows` plugin.
fix
For Windows management, install `pyinfra-windows` separately and use its specific facts/operations.
affects: 3.0.0+
gotchaOperations can fail silently or not execute as expected without clear error messages, especially if conditions (`_if`, `_when`) are not met.
fix
Enable debug mode (`pyinfra --debug`) and verbose output (`pyinfra -vvv`) to trace execution, and carefully review operation conditions.
affects: All
gotchaAn operation might run every time, even if the desired state is already met, indicating a lack of proper idempotency checks.
fix
Ensure operations include logic to check the current state of the host against the desired state. pyinfra operations are generally idempotent by default, but custom `server.shell` commands or incorrect usage can bypass this. Use `--dry` flag to preview changes.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyinfra.operations.apt'
Attempting to import a specific operation directly from `pyinfra.operations` without specifying the operation module (e.g., `apt`).
fix
Import operations from their respective sub-modules, such as `from pyinfra.operations import apt`, then call `apt.packages()`.
pyinfra.exceptions.ConnectError: SSH connection failed: Permission denied (publickey,password).
Incorrect SSH credentials, missing SSH keys, or issues with SSH agent forwarding when connecting to a remote host.
fix
Verify your SSH configuration (`~/.ssh/config`), ensure your SSH agent is running and has the correct keys, or provide explicit `--ssh-user` and `--ssh-password` (or `--ssh-password-prompt`) arguments to the `pyinfra` CLI.
Operation doesn't execute or fails without error messages in pyinfra output.
The operation's `_if` or `_when` conditions were not met, causing it to be skipped, or an underlying command failed silently.
fix
Run pyinfra with `--debug` and `--log-level debug` flags. Check the conditions on the operation. If it's a `server.shell` operation, inspect the `stdout` and `stderr` after execution for clues.
pyinfra reports 'no changes' but the desired state is not met, or 'changes' when no changes should occur.
The facts gathered by pyinfra do not accurately reflect the host's state, or the operation's logic for detecting changes is flawed.
fix
Debug facts by inspecting `host.get_fact(FactName)` results directly. For operations, use the `--dry` flag to see what commands *would* be run, and review the operation's source or implement explicit state checks.
Upgrade
Version history
3.9.2latest on PyPI · released Jun 7, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
30 hits · last 30 days
node
28
OpenAI (training)
1
Resources
pyinfra — pip install pyinfra · libregistry