pyinfra

Execute a command over SSH

$ pyinfra [target_ip_address] exec -- [command_name_and_arguments]

$ pyinfra [path/to/target_list.py] [path/to/deploy.py]

$ pyinfra @local [path/to/deploy.py]

$ pyinfra @docker/[container] [path/to/deploy.py]

pyinfra [GLOBAL_OPTIONS] <inventory> [OPERATION_ARGS]

<inventory>
    Specifies the hosts to operate on. This can be a Python file defining hosts, a directory containing hosts, a simple text file, or a direct host string (e.g., 'myhost.com').

<OPERATION_ARGS>
    Arguments defining the operations to run, typically a Python deploy script (e.g., 'deploy.py').

--version
    Show pyinfra's version number and exit.

--help
    Show this help message and exit.

--user <user>
    Connect to remote hosts as this user (for SSH connections).

--port <port>
    Connect to remote hosts on this port (for SSH connections, default: 22).

--key <path>
    Path to an SSH private key file for authentication.

--password <pass>
    SSH password for authentication. Not recommended for production due to security implications.

--sudo
    Execute operations using 'sudo' on remote hosts.

--sudo-user <user>
    Execute 'sudo' operations as this user (requires --sudo).

--debug
    Enable debug logging output for detailed information.

--dry
    Perform a 'dry run', showing what operations would be executed without making any changes.

--limit <hosts>
    Limit operations to a subset of hosts specified in the inventory (e.g., 'host1,host2' or '@group_name').

--parallel <num>
    Number of parallel connections to use when executing operations (default: 10).

--operations-directory <path>
    Specify a directory containing custom pyinfra operations.

--chdir <path>
    Change the working directory before executing the deployment script.

pyinfra is a powerful, agentless infrastructure automation tool written in Python. It allows users to define infrastructure state and operations using pure Python code, making it highly flexible and extensible. Unlike many other configuration management tools that rely on DSLs or YAML, pyinfra leverages the full power of Python, enabling complex logic and integrations. It connects to target hosts via SSH, Docker, or local connections, and executes operations to achieve the desired state, such as installing packages, configuring files, running commands, and managing services. pyinfra aims for simplicity, speed, and a Pythonic user experience, making it suitable for tasks ranging from small ad-hoc scripts to large-scale deployments across many servers.

While pyinfra offers powerful Pythonic control, its community and ecosystem are smaller compared to more established tools like Ansible or SaltStack.
Users need a basic understanding of Python to write and understand pyinfra operations, as it does not rely on a declarative YAML or DSL syntax for operations.
For very large or complex environments, careful structuring of Python code is essential to maintain readability and manageability.

pyinfra operates on an agentless model, meaning it does not require any special software or agents to be installed on the target servers. It primarily uses SSH for remote execution, offering a secure and widely adopted method for managing infrastructure. It also supports local execution and Docker container connections, providing flexibility for various environments.

One of pyinfra's distinguishing features is its use of pure Python for defining operations and deployments. This provides users with the full power of a general-purpose programming language, allowing for complex conditional logic, loops, custom data structures, and seamless integration with other Python libraries, significantly enhancing its capabilities beyond typical declarative configuration files.

pyinfra is designed to be highly extensible. Users can easily create and share custom operations ('ops') and 'facts' (system information gathering functions) using standard Python modules. This allows for tailored automation solutions that can adapt to unique infrastructure requirements and integrate with specific tools or APIs not covered by the built-in operations.

pyinfra was created by Nick Dickens and first released in 2018. It emerged as an effort to build a simpler, faster, and more Pythonic alternative to existing configuration management tools. The project has seen continuous development, focusing on performance, ease of use, and a strong emphasis on leveraging native Python capabilities for defining infrastructure state, rather than domain-specific languages or YAML-based configurations. It has steadily grown in popularity within the Python community for its unique approach to infrastructure automation.

ansible(1), salt(1), fabric(1), chef(1), puppet(8)