Required Arguments
Defines the target hosts. Can be:
- A Python inventory file (e.g.,
inventory.py) - A single hostname (e.g.,
host.example.com) - Comma-separated hostnames (e.g.,
host1.com,host2.com,@local)
Specifies what to execute. Can be:
- One or more deploy files (e.g.,
deploy.py) - An operation call (e.g.,
server.user pyinfra) - An exec command (e.g.,
exec -- echo hello) - A fact query (e.g.,
fact server.LinuxName) - Debug command (
debug-inventory)
Output & Verbosity
Increase verbosity. Can be repeated up to 3 times:
-v: Print meta information and noop operations-vv: Print input (commands sent to hosts)-vvv: Print output (command results from hosts)
Don’t execute operations on target hosts. Shows what would be changed without making actual changes.Example:
Show differences when changing text files and templates. Useful for reviewing file changes before applying.Example:
Execution Control
Execute operations immediately without prompts or change detection. Can also be set via
PYINFRA_YES environment variable.Example:Restrict target hosts by name or group name. Supports wildcards. Can be specified multiple times.Examples:
Percentage of hosts that need to fail before exiting early. Default behavior prompts on any failure when not using
-y.Example:Number of operations to run in parallel. Controls concurrent execution across hosts.Example:
Run operations in serial, host by host, instead of operation by operation.Example:
Don’t wait between operations for hosts. Executes operations immediately without delays.Example:
Number of times to retry failed operations.Example:
Delay in seconds between retry attempts.Example:
Data & Configuration
Override data values in format
key=value. Can be specified multiple times. Values are automatically parsed (booleans, numbers, strings).Examples:Paths to load additional group data from. Overrides matching keys. Can be specified multiple times.Example:
Specify config file to use instead of default
config.py.Example:Set the working directory before executing. All relative paths will be resolved from this directory.Example:
Authentication & Privilege
Execute operations with sudo (as root or another user).Example:
Which user to sudo to when using
--sudo.Example:Use a password with sudo. pyinfra will prompt for the password.Example:
All hosts have the same sudo password, so ask only once instead of per-host.Example:
Which user to su to for privilege escalation (alternative to sudo).Example:
Shell to use for command execution. Examples:
sh, bash, cmd, ps (PowerShell).Examples:SSH Connection
SSH user to connect as.Example:
SSH port to connect to.Example:
SSH private key filename for authentication.Example:
SSH private key password if the key is encrypted.Example:
SSH password for authentication (less secure than key-based auth).Example:
The non-prefixed variants (
--user, --port, --key, etc.) are deprecated and may be removed in future versions. Use the --ssh-* prefixed versions instead.Debug & Development
Print debug logs from pyinfra. Shows detailed internal operations.Example:
Print debug logs from all packages including pyinfra. Very verbose output.Example:
Print facts after generating operations and exit without executing. Useful for debugging fact collection.Example:
Print operations after generating and exit without executing. Shows the operation plan.Example:
Information & Help
Show help message and exit.Example:
Show pyinfra version and exit.Example:
Print useful information for support (version, Python version, platform) and exit.Example: