Skip to main content
pyinfra’s API enables you to use pyinfra programmatically in Python scripts and applications. This allows you to build custom deployment tools, integrate with other systems, and create reusable infrastructure components.

​
Core Components

The pyinfra API is organized into several key modules:

​
Operations & Deploys

  • @operation - Decorator for creating custom operations
  • @deploy - Decorator for creating reusable deploy functions
  • add_op - Programmatically add operations to state
  • add_deploy - Programmatically add deploys to state

​
State Management

  • State - Manages the state of a pyinfra deployment
  • Inventory - Represents a collection of target hosts
  • Host - Represents a single target host
  • Config - Configuration options for deployments

​
Commands

​
Connectors

Connectors handle communication with target hosts:
  • SSH - Connect via SSH (default)
  • Local - Execute on local machine
  • Docker - Execute in Docker containers
  • Terraform - Generate inventory from Terraform
  • Vagrant - Generate inventory from Vagrant

​
Facts

Facts gather information about target hosts:

​
Quick Start

Here’s a simple example using the pyinfra API: 
from pyinfra import Config, Inventory, State
from pyinfra.operations import server

# Create inventory with target hosts
inventory = Inventory(
    ([
        "server1.example.com",
        "server2.example.com",
    ], {})
)

# Create config
config = Config(
    SUDO=True,
)

# Initialize state
state = State(inventory, config)
state.init(inventory, config)

# Connect to hosts
for host in inventory:
    host.connect()

# Add operations
server.shell(
    name="Hello from pyinfra API!",
    commands=["echo 'Hello World'"],
    state=state,
    host=inventory,
)

# Execute operations
from pyinfra.api.operations import run_ops
run_ops(state)

​
CLI vs API Mode

pyinfra operates in two modes:
  • CLI Mode - When running pyinfra command-line tool
  • API Mode - When using pyinfra as a Python library
Some functions behave differently depending on the mode:
  • add_op() and add_deploy() should only be called in API mode
  • Operations automatically execute immediately in API mode when called during the execute phase

​
Context Management

pyinfra uses context variables to track the current state, host, and config: 
from pyinfra.context import ctx_state, ctx_host, ctx_config

# Access current context
state = ctx_state.get()
host = ctx_host.get()
config = ctx_config.get()

​
Type Safety

pyinfra includes type hints for better IDE support and type checking: 
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pyinfra.api import State, Host

def my_deploy(state: "State", host: "Host") -> None:
    # Type-safe operations
    pass

​
Next Steps

Explore the detailed API reference:
  • Operations - Create custom operations
  • Deploy - Create reusable deploys
  • State - Understand state management
  • Host - Work with individual hosts
  • Inventory - Manage host collections

Build docs developers (and LLMs) love

Get started for freeTalk to us