Pyinfra – simple infrastructure automation in Python

Adrian, a Python developer and maintainer of the reader feed library, demonstrated pyinfra, an open-source infrastructure automation tool that turns Python code into shell commands and runs them on many servers over SSH in parallel, at a local DevOps meetup in November 2026. The demo deployed two websites — a landing page and a Python web app — first on a local virtual machine and then on two remote servers using only Python code. Adrian said pyinfra is declarative and idempotent like Ansible but uses Python instead of YAML, and in his limited small-scale testing it was faster than Ansible with the Mitogen plugin, though pyinfra has fewer built-in operations and a smaller ecosystem after 10 years.

pyinfra – simple infrastructure automation in Python November 2026 ∙ 15 minute read ∙ Hi, I'm Adrian, and today I will live demo pyinfra https://pyinfra.com/ , an infrastructure automation tool. We will deploy two websites – a landing page and a Python web app – first on a local virtual machine, and then on two remote servers, using only Python code. Note This is the edited transcript of a talk I gave at a local DevOps meetup. While part of the "live" aspect is lost in writing, I think it's a pretty decent pyinfra tutorial, so you are welcome to follow along at home. About me about-me Before we talk about pyinfra, I should introduce myself https://death.andgravity.com/about . I worked at a Fortune 10 company for most of my career, where I did site reliability engineering for the reverse proxy behind some really big websites and two thousand smaller ones, and where I built a data-lake-plus-feature-store for an ML organization. In my spare time, I write about Python on this website https://death.andgravity.com/ , and I maintain the creatively named reader https://github.com/lemon24/reader , a Python feed reader library and web app. Lately I've been working on a hosted version of reader https://death.andgravity.com/reader-3-23 hosted-reader-status-update , which is how I ended up using pyinfra. What is pyinfra? what-is-pyinfra pyinfra https://pyinfra.com/ is a mostly command-line tool that turns Python code into shell commands and runs them on many servers over SSH, in parallel. Think Ansible, but simpler. for user in 'admin', 'alice', 'bob' : server.user user files.put 'files/hello.txt', '/etc/motd' if host.data.get 'install postgres' : apt.install 'postgresql' Why use pyinfra? why-use-pyinfra I chose pyinfra because, like Ansible <https://en.wikipedia.org/wiki/Ansible software , it is declarative – you describe what a server should look like, and pyinfra makes it so – and idempotent – nothing happens if the server is already in the desired state. Unlike Ansible, there's no YAML – deploys playbooks are Python code, which means you can do anything Python code can do: you can have for s and if s, you can have code completion and type checking, and you can even import libraries. Of interest to people using Ansible at larger scales, pyinfra is also faster; in my limited, small-scale experience, it was faster than Ansible with the Mitogen https://mitogen.networkgenomics.com/ansible detailed.html plugin. In fairness to Ansible, while pyinfra has been around for 10 years, it has fewer built-in operations modules and a smaller ecosystem, although that's partially offset by how easy it is to write custom operations. When to use pyinfra? when-to-use-pyinfra pyinfra use cases follow from what it does – configuring servers over SSH. As such, pyinfra is good for boring, cloud-agnostic architectures, from lots of servers with different roles all the way down one-computer programming https://crawshaw.io/blog/one-process-programming-notes , where it still makes deploys reproducible and prevents drift. 1 fn-1 It is pretty easy to learn too, so it's a good fit for self-hosting and home servers, and even if you don't use it for configuration management, pyinfra gives you a convenient way of running ad-hoc commands on fleets of servers. 2 fn-2 The simplicity comes with limitations: fully-automated pipelines are extra work, and care is needed if multiple people run deploys at the same time. Nevertheless, you can get pretty far if you structure your deploys well, and there's a Python API https://docs.pyinfra.com/en/3.x/api/index.html for building stuff on top. The demo the-demo I'll try to focus on the interesting parts, but you can find the entire code on GitHub https://github.com/lemon24/pyinfra-demo . At the end of the demo, we'll have two websites, a landing page and a Python web app, deployed in two stages – a local virtual machine for beta: .--- pyinfra.local ---.- app.pyinfra.local -. | nginx | | static website : Python web app | '-------------------------------------------' ...and two separate servers for prod: .--- pyinfra.a.c ----. .- app.pyinfra.a.c --. | nginx | | nginx | | static website | | Python web app | '--------------------' '--------------------' Here's a sneak peek of the final deploy: apt.update name="apt update", cache time=24 3600 apt.packages 'nginx', 'python3-certbot-nginx' , name="install nginx" disable default = files.link name="disable default site", path='/etc/nginx/sites-enabled/default', present=False, server.service name="reload nginx", service='nginx', reloaded=True, if=disable default.did change, if host.data.get 'home domain' : local.include 'tasks/home.py' if host.data.get 'app domain' : local.include 'tasks/app.py' Operations and facts operations-and-facts First, we should get familiar with two basic pyinfra concepts. Operations change the server in some way; most are declarative and idempotent, and you use them to ensure state . A Python file containing operations is called a deploy . Here's a simple deploy with one operation https://docs.pyinfra.com/en/3.x/operations/files.html files-file that says "I want hello.txt to exist": python from pyinfra.operations import files files.file 'hello.txt', present=True If we run this deploy below, on my @local machine , we see a list of all the operations and on which hosts they will produce changes, and are asked to approve them: php $ pyinfra @local examples/create file.py -- Loading config... -- Loading inventory... -- Connecting to hosts... @local Connected -- Preparing operation files... Loading: examples/create file.py @local Ready: examples/create file.py -- Detected changes: Operation Change Conditional Change files.file hello.txt, present=True 1 @local - ... Press enter to execute... If we do, we see the operations running and their outcomes: php Press enter to execute... Enter -- Beginning operation run... -- Starting operation: files.file hello.txt, present=True @local Success -- Results: Operation Hosts Success Error No Change files.file hello.txt, present=True 1 1 - - Grand total 1 1 - - -- Disconnecting from hosts... And now hello.txt exists: bash $ ls hello.txt hello.txt Since files.file https://docs.pyinfra.com/en/3.x/operations/files.html files-file is idempotent, nothing happens if we run the deploy again: php $ pyinfra @local examples/create file.py ... -- Detected changes: Operation Change Conditional Change files.file hello.txt, present=True - - ... -- Beginning operation run... -- Starting operation: files.file hello.txt, present=True @local No changes ... Facts gather data about the target host; you use them to control operations. Here's a deploy that installs the Apache web server: python from pyinfra import host from pyinfra.facts.server import LinuxName from pyinfra.operations import server if host.get fact LinuxName in 'Ubuntu', 'Debian' : server.packages 'apache2' else: server.packages 'httpd' The package is usually called httpd , but Debian-based distributions call it apache2 , so we use the LinuxName https://docs.pyinfra.com/en/3.x/facts/server.html server-LinuxName fact to detect where we are and pass the right name to the server.packages https://docs.pyinfra.com/en/3.x/operations/server.html server-packages operation. My machine is a Mac, so the httpd branch is chosen: 3 fn-3 php $ pyinfra @local examples/install apache.py --dry ... -- Detected changes: Operation Change Conditional Change server.packages httpd 1 @local - ... Where are the commands? where-are-the-commands Before we look at debug output, let's see how pyinfra operations are implemented. Here's a simplified version of the files.file implementation https://github.com/pyinfra-dev/pyinfra/blob/v3.10.0/src/pyinfra/operations/files.py L1663-L1762 : python @operation def file path: str, present: bool = True : info = host.get fact File, path=path if info is None and present: yield f"touch {quote path }" elif info and not present: yield f"rm -f {quote path }" The structure is similar for all operations: read the host state using facts, diff it against the desired state, and return commands to reach the desired state if they don't match. Here's another deploy that says "I want hello.txt to not exist": python from pyinfra.operations import files files.file 'hello.txt', present=False With --debug , we can see the commands being run during each execution phase. During the prepare phase before approval , pyinfra runs the deploy code once per host to load operations, and then runs each operation to see if it returns commands, without running the commands themselves this is how "detected changes" works . Running operations runs facts, which results in read-only commands being run: php $ pyinfra @local examples/delete file.py --debug ... -- Preparing operation files... Loading: examples/delete file.py pyinfra.api.operation Adding operation, {'files.file'}, ... pyinfra.api.facts Getting fact: files.File path=hello.txt pyinfra.connectors.local -- Running command on localhost: sh -c ' test -e hello.txt || test -L hello.txt || stat -c '"'"'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N'"'"' hello.txt 2 /dev/null || stat -f '"'"'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY'"'"' hello.txt || ls -ld hello.txt ' pyinfra.api.facts @local Loaded fact files.File path=hello.txt @local Ready: examples/delete file.py -- Detected changes: Operation Change Conditional Change files.file hello.txt, present=False 1 @local - ... Press enter to execute... During the execute phase, pyinfra runs the previously loaded operations again , but this time it runs the commands returned by them too: php Press enter to execute... Enter -- Beginning operation run... -- Starting operation: files.file hello.txt, present=False pyinfra.api.facts Getting fact: files.File path=hello.txt pyinfra.connectors.local -- Running command on localhost: sh -c ' test -e hello.txt || test -L hello.txt || stat -c '"'"'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N'"'"' hello.txt 2 /dev/null || stat -f '"'"'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY'"'"' hello.txt || ls -ld hello.txt ' pyinfra.api.facts @local Loaded fact files.File path=hello.txt pyinfra.connectors.local -- Running command on localhost: sh -c 'rm -f hello.txt' @local Success ... Inventory + nginx setup inventory-nginx-setup So far we've been using my local machine as target host, but we want beta to be as similar to prod as possible, so I've set up an Ubuntu virtual machine with Vagrant https://github.com/lemon24/pyinfra-demo/blob/main/infra/Vagrantfile . Also, you will typically use an inventory file containing groups of hosts instead of passing individual hosts directly to the CLI. For our demo, we need just one group: group name = host1, host2, ... my hosts = 'pyinfra.local' you can have more groups: db servers = 'db-1.net', 'db-2.net' web servers = i.hostname for i in aws.ec2.list instances asg='my-asg' Since the inventory is a Python file, groups don't have to be list literals – you could, for example, import a library and list instances in an autoscaling group dynamically. Here's how you use an inventory to run arbitrary commands: php $ pyinfra inventories/beta.py exec -- lsb release -d ... -- Beginning operation run... -- Starting operation: server.shell lsb release -d pyinfra.local Description: Ubuntu 26.04.1 LTS pyinfra.local Success ... We'll use nginx for both of our websites, which means we need to install it first. Here's what the main deploy looks like minus imports : | infra/deploy.py | | |---|---| | 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | apt.update name="apt update", cache time=24 3600 apt.packages 'nginx', name="install nginx" disable default = files.link name="disable default site", path='/etc/nginx/sites-enabled/default', present=False, server.service name="reload nginx", service='nginx', reloaded=True, if=disable default.did change, | We update the package cache, we install nginx, we disable the default "Welcome to nginx " site, and then we reload the nginx config. To avoid unnecessary reloads, we use the if global argument https://docs.pyinfra.com/en/3.x/arguments.html to reload only if the previous operation actually ran https://docs.pyinfra.com/en/3.x/deploy-process.html checking-operation-changes . In theory, we could use a fact to gate the last two operations instead: apt.packages ... if host.get fact Link, '/etc/nginx/sites-enabled/default' : files.link ... server.service ... ...but that if happens in the prepare phase, when nginx and the symlink hasn't been installed yet, so they would be skipped on the first run. If we run the deploy, no change is detected for "disable default site" no symlink yet : php $ pyinfra inventories/beta.py deploy.py ... -- Detected changes: Operation Change Conditional Change apt update 1 pyinfra.local - install nginx 1 pyinfra.local - disable default site - - reload nginx - 1 pyinfra.local Detected changes may not include every change pyinfra will execute. Hidden side effects of operations may alter behaviour of future operations, this will be shown in the results. The remote state will always be updated to reflect the state defined by the input operations. Press enter to execute... Enter ... -- Results: Operation Hosts Success Error No Change apt update 1 1 - - install nginx 1 1 - - disable default site 1 1 - - reload nginx 1 1 - - ... ...but the operation does run, as the prophecy foretold "side effects of operations may alter behaviour of future operations" . Static site + code reuse static-site-code-reuse With nginx installed, we can proceed to the static home page. We'll put the operations in a separate file that we include in the main deploy, which in addition to keeping code tidy, allows specific tasks to be conditional: | infra/deploy.py | | |---|---| | 23 24 | if host.data.get 'home domain' : local.include 'tasks/home.py' | Host data https://docs.pyinfra.com/en/3.x/inventory-data.html host-data is arbitrary data associated with hosts in the inventory file: group name = host1, {'some custom': 'host data'} , ... my hosts = 'pyinfra.local', { 'home domain': 'pyinfra.local', } , fmt: skip The home page deploy itself is pretty straightforward: | infra/tasks/home.py | | |---|---| | 4 5 6 7 8 9 10 11 12 13 | python from modules import nginx sync files = files.sync name="sync files", src='../home', dest='/opt/home', delete=True, nginx.site 'templates/nginx/home.conf', host.data.home domain | There's one operation that synchronizes files https://docs.pyinfra.com/en/3.x/operations/files.html files-sync from a local directory to a remote one, and another operation that sets up an nginx site using the domain from host data. Except nginx.site isn't actually an operation, but a packaged deploy https://docs.pyinfra.com/en/3.x/api/deploys.html ; besides the function definition that makes it reusable, it looks like any other deploy: | infra/modules/nginx.py | | |---|---| | 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | python @deploy "nginx site" def site template, domain, context : write site = files.template name="write", src=template, dest=f'/etc/nginx/sites-available/{domain}', domain=domain, context, enable site = files.link name="enable", path=f'/etc/nginx/sites-enabled/{domain}', target=f'/etc/nginx/sites-available/{domain}', server.service name="reload", service='nginx', reloaded=True, if=any changed write site, enable site , | files.template https://docs.pyinfra.com/en/3.x/operations/files.html files-template uses Jinja https://jinja.palletsprojects.com/en/stable/ , so we can have a base template for all HTTP sites: server { listen 80; listen :: :80; server name {{ domain }}; {% block server %}{% endblock %} } ...that we then extend with site-specific configuration: {% extends 'templates/nginx/http.conf' %} {% block server -%} location / { root /opt/home; } {%- endblock %} Passing --diff shows the rendered template, which is pretty neat: php $ pyinfra inventories/beta.py deploy.py --diff ... -- Preparing operation files... Loading: deploy.py pyinfra.local Will create /etc/nginx/sites-available/pyinfra.local @@ -0,0 +1,9 @@ + server { + listen 80; + listen :: :80; + server name pyinfra.local; + + location / { + root /opt/home; + } + } pyinfra.local Ready: deploy.py -- Detected changes: Operation Change Conditional Change apt update - - install nginx - - disable default site - - reload nginx - 1 pyinfra.local tasks/home.py | sync files 1 pyinfra.local - tasks/home.py | nginx site | write 1 pyinfra.local - tasks/home.py | nginx site | enable 1 pyinfra.local - tasks/home.py | nginx site | reload - 1 pyinfra.local ... And now we have a static site Web app + secrets web-app-secrets The web application is a simple Flask app that we can install with pip: bash $ tree app app ├── app │ ├── init .py │ ├── static │ │ └── style.css │ └── templates │ └── index.html └── pyproject.toml We serve it using a traditional Gunicorn being nginx on a Unix socket https://gunicorn.org/deploy/ nginx-configuration setup: :80, :443 | .-------------. | nginx | groups: app-socket, www-data '-------------' | app.sock groups: app-socket | .- Gunicorn --. | web app | groups: app-socket, app '-------------' The deploy for it is slightly bigger, but hopefully still straightforward. We have operations to create users and groups: | infra/tasks/app.py | | |---|---| | 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | server.group 'app', name="create app group" server.group 'app-socket', name="create socket group" server.user name="create user", user='app', group='app', groups= 'app-socket' , home="/var/lib/app", shell="/usr/sbin/nologin", system=True, server.user name="nginx socket access", user='www-data', groups= 'app-socket' , append=True, | ...to create a virtual environment with our app and its dependencies: | infra/tasks/app.py | | |---|---| | 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | apt.packages 'python3-venv', name="install venv" pip.venv '/opt/app', 'python3', name="create venv" pip.packages 'gunicorn' , virtualenv='/opt/app', name="install deps" sync files = files.sync name="sync app files", src='../app', dest='/opt/app/src', delete=True, exclude dir= ' / pycache ' , install app = server.shell "/opt/app/bin/pip install /opt/app/src", name="install app", if=sync files.did change, | ...to create and start a systemd service for Gunicorn: | infra/tasks/app.py | | |---|---| | 56 57 58 59 60 61 62 63 64 65 66 67 68 | write service = files.template name="write service", src='templates/systemd/app.service', dest='/etc/systemd/system/app.service', systemd.service name="enable service", service='app.service', enabled=True, restarted=True, daemon reload=True, if=any changed install app, write config, write service , | ...and finally to configure nginx: | infra/tasks/app.py | | |---|---| | 70 | nginx.site 'templates/nginx/app.conf', host.data.app domain | In addition, Flask needs a secret key https://flask.palletsprojects.com/en/stable/config/ SECRET KEY , which usually comes from a config file: | infra/tasks/app.py | | |---|---| | 47 48 49 50 51 52 53 54 | write config = files.template name="write config", src='templates/config.py.jinja', dest='/etc/opt/app/config.py', group='app', mode=640, get secret=secrets.get secret, | The question is, where do we store the secret key before writing the config? The simple and wrong solution is to hardcode it in the deploy or in the template; unencrypted-secrets-in-version-control issue aside, we'd also like the secrets to be different between beta and prod. As I said, a deploy is a Python file, so we can do anything: we can get them from a password https://keyring.readthedocs.io/en/latest/ manager https://keyring.readthedocs.io/en/latest/ third-party-backends , a security key, or even an encrypted https://pypi.org/project/keyrings.cryptfile/ file https://pypi.org/project/privy/ . To illustrate the point, here's a simple function that reads named secrets from an unencrypted JSON file: 4 fn-4 python import json from pyinfra import host secrets path = 'secrets.json' def get secret name, , stage=None : if not stage: stage = host.data.stage with open secrets path as f: data = json.load f if secret := data.get stage, {} .get name : return secret raise RuntimeError f"secret {name r} for stage {stage r} not found" The stage comes from host data, this time not in the inventory, but in a group data file https://docs.pyinfra.com/en/3.x/inventory-data.html group-data-files that applies to all hosts in a group beta , the inventory name, is an implicit group : stage = 'beta' The config template looks like this: SECRET KEY = {{ '{ r}'.format get secret 'app secret key' }} Deploying looks the same, only with way more operations: php $ pyinfra inventories/beta.py deploy.py ... -- Results: Operation Hosts Success Error No Change ... Grand total 23 15 - 8 ... And now we have a web app: HTTPS + prod https-prod That's a nice looking web app, but it would be even nicer if it were not "not secure". This requires HTTPS, which requires a TLS certificate. Fortunately, those are easy to get these days – Let's Encrypt https://en.wikipedia.org/wiki/Let%27s Encrypt provides free certificates, and Certbot https://certbot.eff.org/pages/about will request, install, and renew them automatically. Unfortunately, there's no built-in Certbot operation, so we have to write a custom one: | infra/modules/certbot.py | | |---|---| | 8 9 10 11 12 13 14 | python @operation def certificate domain : if domain in host.get fact Certificates : return yield f"certbot certonly -d {quote domain } -n --nginx --agree-tos" | Like in the initial example where-are-the-commands , we read the host state using a fact and then return commands if it doesn't match the desired state. The fact is custom too: | infra/modules/certbot.py | | |---|---| | 17 18 19 20 21 22 23 24 25 | class Certificates FactBase : default = dict requires command = "certbot" def command self : return "certbot certificates" def process self, output : return {c 'name' : c for c in parse certbot certificates output } | And we already have a convenient place where we can use the operation: | infra/modules/nginx.py | | |---|---| | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | python @deploy "nginx site" def site template, domain, https=None, context : reload ops = if https is None: https = host.data.get 'nginx https' if https: reload ops.append certbot.certificate domain, name="cert" write site = files.template name="write", src=template, dest=f'/etc/nginx/sites-available/{domain}', base=f"templates/nginx/http{'s' if https else ''}.conf", domain=domain, context, | Also unfortunately, Certbot needs a resolvable domain name to work, so we can't test this using the beta virtual machine... but we can always test in prod. ≖‿ ≖ Here's a new inventory with two hosts, each with its own domain and HTTPS enabled: my hosts = 'pyinfra.andgravity.com', { 'home domain': 'pyinfra.andgravity.com', } , 'app.pyinfra.andgravity.com', { 'app domain': 'app.pyinfra.andgravity.com', } , fmt: skip stage = 'prod' nginx https = True I say we just go for it: bash $ pyinfra inventories/prod.py deploy.py --yes ... stuff happens ... One minute later, there are ✨ two new websites ✨ on the internet: 5 fn-5 Questions? questions Coming soon : Anyway, that's it for now. Learned something new today? Share it with others, it really helps 1. And you're bound to have extra dev and pre-prod machines anyway. <sup \ return\ </sup fnref-1 2. Say you have a memory leak during a high traffic period and need to reload stuff once in a while until you can find the root cause. <sup \ return\ </sup fnref-2 3. Deploy deploy code runs once per host, so you could have different branches on different hosts within the same run. <sup \ return\ </sup fnref-3 4. Which you absolutely should not do, use keyrings.cryptfile https://pypi.org/project/keyrings.cryptfile/ instead. <sup \ return\ </sup fnref-4 5. Well, not anymore, there's no point in paying to host this : <sup \ return\ </sup fnref-5