Quickstart

This guide will walk you through installing pyinfra and running your first deployment. You’ll learn the core workflow and deploy a simple web server configuration.

Prerequisites

Before you begin, ensure you have:

Python 3.10 or higher installed
SSH access to a server (or use Docker/local execution)
Basic familiarity with Python and command line

Don’t have a server? No problem! You can use @docker/ubuntu or @local to test pyinfra on your local machine.

Installation

Install pyinfra using your preferred package manager:

uv tool install pyinfra

Verify the installation:

pyinfra --version

If you see a version number, you’re ready to go!

Your First Command

Let’s run a simple command on a target. We’ll use a Docker container for this example:

pyinfra @docker/ubuntu exec -- echo "Hello from pyinfra!"

This command:

Targets a Docker container (@docker/ubuntu)
Executes a shell command (exec)
Runs echo "Hello from pyinfra!"

Understanding the syntax

@docker/ubuntu: The target connector and image
exec: The pyinfra command to execute
--: Separates pyinfra arguments from the shell command
echo "Hello from pyinfra!": The actual command to run

Try Different Targets

# Replace with your server hostname
pyinfra my-server.net exec -- echo "Hello from pyinfra!"

Using Operations

Commands are great for ad-hoc tasks, but pyinfra really shines with operations. Operations are declarative and idempotent. Let’s install a package using the apt.packages operation:

pyinfra @docker/ubuntu apt.packages iftop update=true _sudo=true

This operation:

Installs the iftop package
Updates the apt cache first (update=true)
Runs with sudo privileges (_sudo=true)
Only makes changes if iftop isn’t already installed

Run this command twice - notice the second time it says “no changes”? That’s idempotency in action.

Creating Your First Deploy File

For anything more complex than a single operation, you’ll want to create a deploy file. This is a Python file that defines your infrastructure.

Create a deploy file

Create a file called deploy.py:

deploy.py

from pyinfra.operations import apt, files, server

# Update package lists and upgrade all packages
apt.update(
    name="Update apt cache",
    _sudo=True,
)

# Install essential packages
apt.packages(
    name="Install essential tools",
    packages=["vim", "git", "htop", "nginx"],
    update=True,
    _sudo=True,
)

# Create a simple nginx landing page
files.put(
    name="Deploy custom index.html",
    src="index.html",
    dest="/var/www/html/index.html",
    mode="644",
    _sudo=True,
)

# Ensure nginx is running
server.service(
    name="Ensure nginx is running",
    service="nginx",
    running=True,
    enabled=True,
    _sudo=True,
)

Create the index.html file

Create index.html in the same directory:

index.html

<!DOCTYPE html>
<html>
<head>
    <title>pyinfra deployed this!</title>
</head>
<body>
    <h1>Hello from pyinfra!</h1>
    <p>This page was deployed using pyinfra.</p>
</body>
</html>

Run the deploy

Execute your deploy file:

pyinfra @docker/ubuntu deploy.py

You’ll see output showing each operation and what changes were made:

--> Loading deploy file: deploy.py
--> Loaded operations: 4

--> Executing operations...
[SUCCESS] Update apt cache
[SUCCESS] Install essential tools (4 packages added)
[SUCCESS] Deploy custom index.html (file uploaded)
[SUCCESS] Ensure nginx is running (service started)

--> Results:
    Operations: 4
    Commands: 12
    Errors: 0

Verify it worked

Check that nginx is serving your page:

pyinfra @docker/ubuntu exec -- curl localhost

You should see your HTML page!

Creating an Inventory File

Typing host names on the command line works for quick tasks, but for real deployments you’ll want an inventory file. Create inventory.py:

inventory.py

# Define your hosts
targets = [
    "@docker/ubuntu",  # Docker container
    "web1.example.com",  # Production web server
    ("web2.example.com", {"ssh_port": 2222}),  # Server with custom SSH port
]

# Define groups for organizing hosts
webservers = [
    "web1.example.com",
    "web2.example.com",
]

containers = [
    "@docker/ubuntu",
]

Now run your deploy against the inventory:

pyinfra inventory.py deploy.py

This will execute deploy.py on all hosts defined in inventory.py.

You can limit execution to specific hosts or groups using the --limit flag:

pyinfra inventory.py deploy.py --limit webservers

Dry Run Mode

Before making changes to production servers, use dry run mode to see what would happen:

pyinfra inventory.py deploy.py --dry

This shows all the commands that would be executed without actually running them.

Always test with --dry before deploying to production!

Debugging

Need to see exactly what’s happening? Use verbose output:

# Show operation details
pyinfra inventory.py deploy.py -v

# Show commands being executed
pyinfra inventory.py deploy.py -vv

# Show all output including stderr
pyinfra inventory.py deploy.py -vvv

Using Python Features

Remember, deploy files are just Python! Use all the language features you know:

deploy.py

from pyinfra import host
from pyinfra.operations import apt, server

# Define a reusable function
def install_web_stack(domain):
    apt.packages(
        name=f"Install packages for {domain}",
        packages=["nginx", "certbot"],
        _sudo=True,
    )
    
    files.template(
        name=f"Configure nginx for {domain}",
        src="nginx.conf.j2",
        dest=f"/etc/nginx/sites-available/{domain}",
        domain=domain,  # Pass variables to template
        _sudo=True,
    )

# Use conditionals
if host.get_fact("Os") == "Ubuntu":
    install_web_stack("example.com")

# Loop over data
for port in [80, 443, 8080]:
    server.shell(
        name=f"Open port {port}",
        commands=f"ufw allow {port}",
        _sudo=True,
    )

Understanding the Workflow

Here’s what happens when you run a deploy:

Load inventory

pyinfra loads your inventory file and connects to all target hosts.

Gather facts

For each host, pyinfra gathers facts (OS, packages, files, etc.) to understand current state.

Generate operations

Your deploy file is executed, generating a list of operations to perform.

Generate commands

Each operation compares desired state with current state and generates the minimal shell commands needed.

Execute in parallel

Commands are executed on all hosts in parallel for maximum speed.

Report results

pyinfra shows you what changed (or didn’t) on each host.

Common Operations

Here are some operations you’ll use frequently:

Package Management

from pyinfra.operations import apt

# Install packages
apt.packages(
    packages=["nginx", "postgresql", "redis"],
    update=True,
    _sudo=True,
)

# Remove packages
apt.packages(
    packages=["apache2"],
    present=False,
    _sudo=True,
)

File Management

from pyinfra.operations import files

# Upload a file
files.put(
    src="local-file.txt",
    dest="/remote/path/file.txt",
    mode="644",
)

# Create directory
files.directory(
    path="/opt/myapp",
    user="ubuntu",
    group="ubuntu",
    mode="755",
    _sudo=True,
)

# Use Jinja2 templates
files.template(
    src="config.j2",
    dest="/etc/myapp/config.yaml",
    setting_value="production",
    _sudo=True,
)

Service Management

from pyinfra.operations import server

# Manage systemd services
server.service(
    service="nginx",
    running=True,
    enabled=True,
    restarted=True,  # Restart if running
    _sudo=True,
)

Running Commands

from pyinfra.operations import server

# Execute shell commands
server.shell(
    name="Run custom script",
    commands=[
        "cd /opt/myapp",
        "./setup.sh",
    ],
    _sudo=True,
)

# Run a script
server.script(
    src="scripts/deploy.sh",
    _sudo=True,
)

Next Steps

You’ve learned the basics of pyinfra! Here’s where to go next:

Core Concepts

Deep dive into how pyinfra works

Operations Reference

Explore all 40+ operation modules

Inventory & Data

Learn advanced inventory management

CLI Reference

Master the pyinfra command line

Need Help?

GitHub Discussions

Ask questions and share knowledge

Matrix Chat

Real-time community support

Examples Repository

See real-world examples

Issue Tracker

Report bugs and request features

Get Started

Core Concepts

Guides

CLI Reference

Advanced

Prerequisites

Installation

Your First Command

Try Different Targets

Using Operations

Creating Your First Deploy File

Creating an Inventory File

Dry Run Mode

Debugging

Using Python Features

Understanding the Workflow

Common Operations

Next Steps

Core Concepts

Operations Reference

Inventory & Data

CLI Reference

Need Help?

GitHub Discussions

Matrix Chat

Examples Repository

Issue Tracker

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

Advanced

Documentation Index

​Prerequisites

​Installation

​Your First Command

​Try Different Targets

​Using Operations

​Creating Your First Deploy File

​Creating an Inventory File

​Dry Run Mode

​Debugging

​Using Python Features

​Understanding the Workflow

​Common Operations

​Next Steps

Core Concepts

Operations Reference

Inventory & Data

CLI Reference

​Need Help?

GitHub Discussions

Matrix Chat

Examples Repository

Issue Tracker

Build docs developers (and LLMs) love

Prerequisites

Installation

Your First Command

Try Different Targets

Using Operations

Creating Your First Deploy File

Creating an Inventory File

Dry Run Mode

Debugging

Using Python Features

Understanding the Workflow

Common Operations

Next Steps

Need Help?