Required Arguments
string
required
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)
string
required
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
flag
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)
flag
Don’t execute operations on target hosts. Shows what would be changed without making actual changes.Example:
flag
Show differences when changing text files and templates. Useful for reviewing file changes before applying.Example:
Execution Control
flag
Execute operations immediately without prompts or change detection. Can also be set via
PYINFRA_YES environment variable.Example:string
Restrict target hosts by name or group name. Supports wildcards. Can be specified multiple times.Examples:
integer
Percentage of hosts that need to fail before exiting early. Default behavior prompts on any failure when not using
-y.Example:integer
Number of operations to run in parallel. Controls concurrent execution across hosts.Example:
flag
Run operations in serial, host by host, instead of operation by operation.Example:
flag
Don’t wait between operations for hosts. Executes operations immediately without delays.Example:
integer
default:"0"
Number of times to retry failed operations.Example:
integer
default:"5"
Delay in seconds between retry attempts.Example:
Data & Configuration
string
Override data values in format
key=value. Can be specified multiple times. Values are automatically parsed (booleans, numbers, strings).Examples:string
Paths to load additional group data from. Overrides matching keys. Can be specified multiple times.Example:
string
default:"config.py"
Specify config file to use instead of default
config.py.Example:string
Set the working directory before executing. All relative paths will be resolved from this directory.Example:
Authentication & Privilege
flag
Execute operations with sudo (as root or another user).Example:
string
Which user to sudo to when using
--sudo.Example:flag
Use a password with sudo. pyinfra will prompt for the password.Example:
flag
All hosts have the same sudo password, so ask only once instead of per-host.Example:
string
Which user to su to for privilege escalation (alternative to sudo).Example:
string
Shell to use for command execution. Examples:
sh, bash, cmd, ps (PowerShell).Examples:SSH Connection
string
SSH user to connect as.Example:
integer
SSH port to connect to.Example:
path
SSH private key filename for authentication.Example:
string
SSH private key password if the key is encrypted.Example:
string
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
flag
Print debug logs from pyinfra. Shows detailed internal operations.Example:
flag
Print debug logs from all packages including pyinfra. Very verbose output.Example:
flag
Print facts after generating operations and exit without executing. Useful for debugging fact collection.Example:
flag
Print operations after generating and exit without executing. Shows the operation plan.Example:
Information & Help
flag
Show help message and exit.Example:
flag
Show pyinfra version and exit.Example:
flag
Print useful information for support (version, Python version, platform) and exit.Example: