Chapter 25: Managing Python Projects with Poetry — Part 1

Network automation doesn’t move as one thing. It moves as a noisy convoy of tools and vendor SDKs, each on its own release cadence and with its own opinion about which Python and which transitive dependencies it will tolerate. Your everyday kit, like Ansible for change execution, Nornir for inventory-driven workflows, Scrapli and Netmiko for device sessions, ncclient for NETCONF/YANG operations, plus a sprinkling of vendor SDKs, rarely lines up on the same versions at the same time. That’s the normal state of play, not an exception. And yet most engineers still try to keep this convoy together with a hand-rolled requirements.txt and a silent hope that pip won’t surprise them during a change window.

Pip is an installer, not a contract. It will dutifully fetch “the latest compatible things” every time you run pip install -r requirements.txt, but “compatible” is evaluated on the fly from a sprawling dependency graph that changes underneath you. Last week’s “compatible” is not this week’s. A teammate running the same command on a jump host may end up with a slightly different set of transitive packages than you had in the lab. CI may resolve a different build than staging. Air-gapped recovery drills expose the worst of it: with no lockfile, you don’t actually know which exact wheel versions your automation depended on when it worked. You shipped intent with your code, but left the dependencies to probability.

This is where Poetry earns its keep, especially for network engineers who care about repeatable outcomes. Poetry turns dependency management from guesswork into policy. It gives you a single, auditable source of truth; pyproject.toml describes what you intend to use, and poetry.lock captures exactly what you did use when the system last resolved successfully. That lockfile is the difference between “works on my laptop” and “works everywhere we claim it does”: your lab VM, the shared bastion in production, and the CI runner that gates merges.

Poetry also understands that different parts of your network estate need different stacks, and it lets you express that cleanly. Your Junos/YANG work might live behind ncclient and lxml, while your Cisco playbooks rely on Scrapli/Netmiko, your test harness depends on pytest, pytest-asyncio, and rich for operator-friendly output, which you do not want on the production jump host. With Poetry, you don’t fork repos or maintain brittle comment blocks in a monolithic requirements.txt; you define dependency groups and optional extras that mirror reality. When you install for the lab, you include the lab groups. When you install on the bastion, you bring only the runtime set. When CI builds, it installs exactly what the lockfile says; no more, no less.

Critically, Poetry doesn’t replace the interpreter discipline you established with Pyenv; it sits above it. Pyenv pins which Python (like 3.8 for the production Ansible estate, 3.11 for your NETCONF pipelines, 3.12 for experimental Nornir tasks), while Poetry pins which packages for each of those worlds and records the precise resolution. That two-layer contract (interpreter + locked dependencies) is the operational equivalent of a well-designed underlay with a clear overlay: you trust it because it’s explicit, versioned, and reproducible.

Consider the lifecycle this enables. You set up a new repo for a maintenance window automation: pyenv local 3.9.x to match the approved runtime, poetry init to declare your intent, poetry add to pull in only what you need. Poetry resolves a coherent set of versions and freezes them in the lockfile. You push to Git; your teammate clones it on a different machine and runs poetry install, and they get the exact same environment, byte-for-byte. CI runs the test suite against the same lock; later, you update a single package and run poetry lock to re-resolve intentionally, review the changes in a merge request, and roll that change like any other network policy update. When the platform team asks for a software bill of materials or you practice an air-gapped restore, you can export the environment deterministically and even pre-cache the wheels. Nothing is left to “latest.”

In short, Poetry introduces the three traits network engineers insist on everywhere else: intent, isolation, and reproducibility. It gives automation the same rigor you apply to routing policies and change control. Pip alone will always be a moving target; requirements.txt will always age faster than you can babysit it.

Poetry is how you stop negotiating with transitive dependency drift and start operating your automation like a system, so the lab, the jump host, and CI/CD all see the same thing, every time. And this is what this article will discuss in the sections below.

The easiest way to understand Poetry is to place it in a three-layer stack that mirrors how you already think about networks:

Think of Pyenv as the underlay image on the box, Poetry as the intent system for the overlay (dependency graph + packaging), and pipx as standalone appliances living beside your projects.

1) A single source of truth for your automation stack.
Poetry stores your intent in pyproject.toml (what you want) and the exact resolved state in poetry.lock (what you actually got when it worked). Together, they are a contract between your laptop, the jump host, and CI/CD. If the lockfile is in Git, everyone—humans and robots—installs the same wheels and transitive dependencies, byte-for-byte.

2) A disciplined dependency manager.
poetry add ncclient doesn’t just “grab something compatible today.” It resolves a coherent set of versions, records them in the lockfile (including hashes), and enforces that state on every subsequent poetry install. Your Ansible change window won’t be surprised by an upstream minor release.

3) A project packager.
When your scripts mature into tools, Poetry builds wheels and source distributions (poetry build) and can publish them to internal indexes (poetry publish). That means your SD-WAN SDK, inventory client, or config parser can be consumed like any other first-class dependency across teams.

4) An environment orchestrator, on top of the interpreter you chose.
Poetry can create and manage a virtual environment per project, ideally in-project (e.g., ./.venv/) for portability. It respects whatever interpreter Pyenv puts on your PATH, or you can bind explicitly:

Interpreter selection (Pyenv) and dependency resolution (Poetry) stay cleanly separated.

pip is a great installer. It is not a policy engine. A hand-written requirements.txt expresses some intent (“I think we need these top-level packages”), but leaves transitive resolution to whatever the internet looks like today. Two engineers can run pip install -r requirements.txt a week apart and silently get different transitive versions. You can “freeze the moment” with pip freeze, but that file mixes top-level intent with every transitive pin and often includes machine-specific flotsam. It’s like dumping a router’s running config and calling it a design document.

Poetry separates concerns cleanly:

Operational payoff:

pip-tools (pip-compile / pip-sync) is a solid middle ground when you want to stay in the pip universe:

Where Poetry and pip-tools differ:

If your team already standardized on pip-tools, you can stay there and still apply Pyenv for interpreters. But Poetry gives you a cohesive lifecycle: declare, lock, install, run, build, publish, under one tool, with strong semantics for groups/extras that map cleanly to network use cases (e.g., --with junos --without cisco).

In networking, we don’t ship “vibes”; we ship intent that can be reconciled. Poetry applies the same rigor to dependencies:

With both files versioned:

This isn’t a ceremony. It’s the difference between “my Nornir pipeline acted weird last night” and “we know exactly which dependency set ran and why.” Pyenv nails the interpreter. Poetry nails the packages. Pipx keeps global CLIs from leaking. Together, you get the boring determinism your automation deserves, so you can spend your time solving network problems, not negotiating with dependency drift.

A great pyproject.toml reads like a design document for your automation stack: it declares the Python you run on, lists what you depend on (at the top level), captures exactly what was resolved (in the lockfile), and encodes the knobs you need for multi-vendor work (groups, extras, internal indexes, and entry points). Below is a realistic template tuned to a network engineer’s day-to-day, followed by the rationale behind each choice.

You’ve already pinned the interpreter with Pyenv, but declaring it here ensures:

These form the platform layer of your automation:

Keep these as top-level intent. Poetry will write the resolved graph (versions + hashes) to poetry.lock. That file is your compiled overlay; reviewed, versioned, and identical across laptops, jump hosts, and CI.

[tool.poetry.extras] lets consumers install feature bundles, e.g.:

This is perfect when your project is a library/CLI that other teams will consume; extras become modular capabilities akin to enabling a feature set per platform.

Groups keep your environments lean and purposeful:

Usage is explicit:

Expose operator tasks as commands:

Many enterprises mirror PyPI or host internal packages (e.g., company-sdwan-sdk). Declaring sources:

Authentication belongs outside pyproject.toml (use Poetry’s config or env vars like POETRY_HTTP_BASIC_CORP_INTERNAL_USERNAME/PASSWORD). Keep secrets out of Git.

Your stacks don’t stand still. Vendors rev APIs, security patches drop mid-quarter, CI images update. A disciplined pyproject.toml gives you:

Treat the file as you treat a routing policy: intent is readable, compilation is reviewable, and both are versioned. That’s how automation grows from scripts to a platform you trust.

The goal here is to make your Poetry setup boring and correct: repeatable on laptops, jump hosts, and CI. We’ll (1) install Poetry in a clean way, (2) force in-project virtualenvs so the environment travels with the repo, (3) bind Poetry to the exact interpreter Pyenv selected, and (4) ship a tiny bootstrap you can reuse across repos.

Think of this as bringing underlay discipline to your tooling: predictable, versioned, and easy to audit.

Pick the interpreter you want this repo to run on and make it explicit:

Commit .python-version, so teammates and CI align to the same minor build.

Recommended (isolate the tool): via pipx

Alternative: official installer

By default Poetry puts virtualenvs in a central cache. For network teams, in-project (./.venv/) is more portable and IDE-friendly. You can enforce this per project (committed) or globally (per user):

I also recommend telling Poetry to respect the interpreter you already activated with Pyenv:

Even with the config above, be explicit the first time you wire a project:

New repo:

Existing repo you just cloned:

From now on, run tools and scripts through Poetry:

Drop this at the repo root, commit it, and tell teammates: “clone → run bootstrap → done.”

Usage:

Get this right once, and it disappears: Poetry uses the Pyenv interpreter you intended, builds a repo-local environment, and every human and robot that touches the repo can recreate it deterministically. That’s the foundation you want before you layer on vendor SDKs, playbooks, and orchestration logic.

But we're not finished yet! There are still other important topics about Poetry to discuss, which will be covered in future editions of this Packets & Python series.

See you there!

Leonardo Furtado