Operations Overview

Operations are the core of pyinfra - they define the state you want your systems to be in. Each operation is idempotent by default and can be used to manage packages, files, services, and more.

What are Operations?

Operations are Python functions that:

Define the desired state of system resources
Generate commands to achieve that state
Are idempotent (can be run multiple times safely)
Return information about changes made

Package Manager Operations

Pyinfra supports a wide range of package managers across different operating systems:

Linux Package Managers

apt

Debian/Ubuntu package management with apt-get

yum

RHEL/CentOS package management with yum

dnf

Fedora/RHEL 8+ package management with dnf

apk

Alpine Linux package management

pacman

Arch Linux package management

zypper

openSUSE package management

BSD Package Managers

pkg

FreeBSD/OpenBSD/NetBSD package management

macOS Package Managers

brew

Homebrew package management for macOS

Windows Package Managers

choco

Chocolatey package management for Windows

Language-Specific Package Managers

pip

Python package management with pip

pipx

Python application management with pipx

npm

Node.js package management with npm

gem

Ruby gem package management

cargo

Rust package management with cargo

Common Patterns

Installing Packages

from pyinfra.operations import apt

apt.packages(
    name="Install web server packages",
    packages=["nginx", "certbot"],
    update=True,
)

Version Pinning

Most package managers support version pinning:

# apt uses = for versions
apt.packages(
    packages=["nginx=1.18.0-0ubuntu1"],
)

# npm uses @ for versions
npm.packages(
    packages=["[email protected]"],
)

Ensuring Latest Versions

apt.packages(
    name="Ensure latest versions",
    packages=["vim", "git"],
    latest=True,
)

Operation Arguments

Most operations share common arguments:

name: Description of what the operation does (optional but recommended)
packages: List of packages to manage
present: Whether packages should be installed (default: True)
latest: Whether to upgrade to latest version
update: Run package index update before installing

Best Practices

Always use descriptive names

# Good
apt.packages(
    name="Install PostgreSQL database server",
    packages=["postgresql", "postgresql-contrib"],
)

# Less helpful
apt.packages(
    packages=["postgresql", "postgresql-contrib"],
)

Update package indexes when needed

apt.packages(
    name="Install packages with fresh index",
    packages=["nginx"],
    update=True,
    cache_time=3600,  # Cache for 1 hour
)

Pin versions for reproducibility

pip.packages(
    name="Install specific versions for production",
    packages=[
        "django==4.2.0",
        "psycopg2==2.9.5",
    ],
)

Overview

Package Managers

Language Packages

Service Management

System Operations

Containers

Databases

Version Control

Security

​What are Operations?

​Package Manager Operations

​Linux Package Managers

apt

yum

dnf

apk

pacman

zypper

​BSD Package Managers

pkg

​macOS Package Managers

brew

​Windows Package Managers

choco

​Language-Specific Package Managers

pip

pipx

npm

gem

cargo

​Common Patterns

​Installing Packages

​Version Pinning

​Ensuring Latest Versions

​Operation Arguments

​Best Practices

​Next Steps