Config

The Config class defines configuration options that control how pyinfra executes operations, connects to hosts, and handles errors.

Creating a Config

Create a config object with custom settings:

from pyinfra import Config

# Use defaults
config = Config()

# Custom configuration
config = Config(
    SUDO=True,
    SUDO_USER="root",
    PARALLEL=10,
    FAIL_PERCENT=25,
    CONNECT_TIMEOUT=30,
)

Configuration Options

Execution Control

int

default:"auto"

Number of parallel operations. Defaults to 20 × CPU cores, capped by system file limits.

int | None

default:null

Maximum percentage of hosts that can fail before stopping. None means no limit.

int

default:10

Timeout in seconds for SSH connections.

Privilege Escalation - sudo

bool

default:false

Whether to use sudo for operations.

str | None

default:null

User to sudo as. None means root.

str | None

default:null

Password for sudo authentication.

Use sudo with login shell (-i flag).

bool

default:false

Preserve environment when using sudo (-E flag).

Privilege Escalation - su

str | None

default:null

User to switch to using su.

str | None

default:null

Password for su authentication.

Use su with login shell (- flag).

bool

default:false

Use su with shell (-s flag).

bool

default:false

Preserve environment when using su (-p flag).

Privilege Escalation - doas

bool

default:false

Whether to use doas for operations (BSD/OpenBSD systems).

str | None

default:null

User to doas as.

Shell & Execution

str

default:"sh"

Shell to use for command execution.

bool

default:false

Show errors but don’t count as failures.

bool

default:false

Show full file diffs for file operations.

Retry Logic

int

default:0

Number of times to retry failed operations.

int

default:5

Delay in seconds between retry attempts.

Temporary Files

str | None

default:null

Temporary directory on remote hosts. None uses host’s $TMPDIR or falls back to DEFAULT_TEMP_DIR.

str

default:"/tmp"

Default temporary directory when TEMP_DIR is not set.

Version Requirements

str | None

default:null

Required pyinfra version (PEP 440 specifier).

str | list | None

default:null

Required packages (PEP 440 specifiers or requirements file path).

Using Configuration

In State

from pyinfra import Inventory, Config, State

inventory = Inventory((["host1"], {}))
config = Config(SUDO=True, PARALLEL=5)

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

Per-Operation Override

Configuration can be overridden per operation:

from pyinfra.operations import server

# Use config defaults
server.shell(commands=["whoami"])

# Override for this operation
server.shell(
    commands=["whoami"],
    _sudo=True,
    _sudo_user="postgres",
    _ignore_errors=True,
)

In Inventory Data

Configuration can be set via inventory data:

from pyinfra import Inventory

inventory = Inventory(
    ([
        ("host1", {"ssh_user": "ubuntu"}),
    ], {
        "SUDO": True,
        "SUDO_USER": "root",
    })
)

Config Methods

Get Current State

Get all current configuration values:

config_state = config.get_current_state()
for key, value in config_state:
    print(f"{key}: {value}")

Set Current State

Set configuration from state:

config.set_current_state([
    ("SUDO", True),
    ("PARALLEL", 10),
])

Lock and Reset State

Lock configuration and restore later:

# Save current state
config.lock_current_state()

# Modify config
config.SUDO = True
config.PARALLEL = 20

# Restore locked state
config.reset_locked_state()

Copy Config

Create a copy of the configuration:

original_config = Config(SUDO=True)
config_copy = original_config.copy()

# Modify copy without affecting original
config_copy.PARALLEL = 10

Version Requirements

Require Specific pyinfra Version

config = Config(
    REQUIRE_PYINFRA_VERSION=">=3.0,<4.0"
)

This uses PEP 440 version specifiers:

">=3.0" - Version 3.0 or higher
">=3.0,<4.0" - Version 3.x only
"==3.1.2" - Exact version

Require Packages

# Require specific packages
config = Config(
    REQUIRE_PACKAGES=[
        "requests>=2.28.0",
        "jinja2>=3.0",
    ]
)

# Or use requirements file
config = Config(
    REQUIRE_PACKAGES="requirements.txt"
)

Environment Variables

Pass environment variables to commands:

config = Config(
    ENV={
        "PATH": "/custom/bin:$PATH",
        "DEBIAN_FRONTEND": "noninteractive",
    }
)

Complete Example

Here’s a complete example with comprehensive configuration:

from pyinfra import Inventory, Config, State
from pyinfra.operations import server, apt

# Production configuration
production_config = Config(
    # Execution
    PARALLEL=10,
    FAIL_PERCENT=10,  # Stop if >10% hosts fail
    CONNECT_TIMEOUT=30,
    
    # Privilege escalation
    SUDO=True,
    SUDO_USER="root",
    PRESERVE_SUDO_ENV=True,
    
    # Retry logic
    RETRY=3,
    RETRY_DELAY=10,
    
    # Shell configuration
    SHELL="bash",
    IGNORE_ERRORS=False,
    DIFF=True,  # Show file diffs
    
    # Temporary files
    TEMP_DIR="/var/tmp",
    
    # Environment
    ENV={
        "DEBIAN_FRONTEND": "noninteractive",
        "PYTHONUNBUFFERED": "1",
    },
    
    # Version requirements
    REQUIRE_PYINFRA_VERSION=">=3.0",
    REQUIRE_PACKAGES=[
        "jinja2>=3.0",
    ],
)

# Development configuration
dev_config = Config(
    PARALLEL=2,
    SUDO=True,
    IGNORE_ERRORS=True,  # Don't stop on errors in dev
    SHELL="bash",
)

# Use configuration
inventory = Inventory((["host1", "host2"], {}))
state = State(inventory, production_config)
state.init(inventory, production_config)

# Operations use config settings
server.shell(
    name="Update system",
    commands=["apt-get update"],
    # Uses SUDO=True from config
)

# Override config for specific operation
server.shell(
    name="Check as user",
    commands=["whoami"],
    _sudo=False,  # Override config
)

apt.packages(
    name="Install packages",
    packages=["nginx", "postgresql"],
    update=True,
    # Uses SUDO=True and RETRY=3 from config
)

Configuration Priority

Configuration is applied in this order (highest to lowest priority):

Operation-level arguments (_sudo=True)
Host data configuration
Group data configuration
Inventory global data
Config object settings
Default values

Source Reference

Location: src/pyinfra/api/config.py:203

Key Classes

Config - Main configuration class (line 203)
ConfigDefaults - Default values (line 20)

Default Values

All defaults are defined in ConfigDefaults (line 20) and can be viewed in the source.

Overview

Core API

Commands

Connectors

Facts

Creating a Config

Configuration Options

Execution Control

Privilege Escalation - sudo

Privilege Escalation - su

Privilege Escalation - doas

Shell & Execution

Retry Logic

Temporary Files

Version Requirements

Using Configuration

In State

Per-Operation Override

In Inventory Data

Config Methods

Get Current State

Set Current State

Lock and Reset State

Copy Config

Version Requirements

Require Specific pyinfra Version

Require Packages

Environment Variables

Complete Example

Configuration Priority

Source Reference

Key Classes

Default Values

​Creating a Config

​Configuration Options

​Execution Control

​Privilege Escalation - sudo

​Privilege Escalation - su

​Privilege Escalation - doas

​Shell & Execution

​Retry Logic

​Temporary Files

​Version Requirements

​Using Configuration

​In State

​Per-Operation Override

​In Inventory Data

​Config Methods

​Get Current State

​Set Current State

​Lock and Reset State

​Copy Config

​Version Requirements

​Require Specific pyinfra Version

​Require Packages

​Environment Variables

​Complete Example

​Configuration Priority

​Source Reference

​Key Classes

​Default Values

Creating a Config

Configuration Options

Execution Control

Privilege Escalation - sudo

Privilege Escalation - su

Privilege Escalation - doas

Shell & Execution

Retry Logic

Temporary Files

Version Requirements

Using Configuration

In State

Per-Operation Override

In Inventory Data

Config Methods

Get Current State

Set Current State

Lock and Reset State

Copy Config

Version Requirements

Require Specific pyinfra Version

Require Packages

Environment Variables

Complete Example

Configuration Priority

Source Reference

Key Classes

Default Values