Nornir mid-term roadmap — seven proposals, open for discussion

[dgarros]

Today we want to share our plan for the next phase of Nornir: the direction, the reasoning behind it, and the process we will follow. The details live in seven proposals, one GitHub issue each. The design discussion happens in those issues.

Nothing here is final. The proposals are our current thinking, written with enough detail so that you can challenge them. That is why we publish them now, before the code is settled.

The direction in one paragraph

Nornir's architecture does not change. It has always been the same idea: a small core that loads an inventory and runs tasks across it concurrently, and everything else (transports, inventory sources, output) handled by plugins. This roadmap keeps that idea. It makes the existing plugin types more capable: runners gain async, streaming, timeouts and cancellation; connection, inventory and processor plugins gain async. And it adds typed contracts where today there are only conventions. One rule applies everywhere: the core ships the protocol, the entry point and a default; every implementation ships as a plugin. "Batteries excluded" stays. It is the constraint the whole roadmap is built around.

The themes

Modern Python and typing. Nornir adopted strict typing early, and we want to go further: typing.Protocol contracts for every new plugin surface, typed inputs and outputs where today there are loose kwargs and untyped results, and named errors that tell you what to do instead of a raw AttributeError. This theme runs through every proposal below.

Native async support. Async is now the standard way to write I/O-bound Python, and Nornir should support it natively, so that you can embed it in an async application, connect to async transports, and scale beyond what threads allow. This arrives as new, opt-in surface: an async runner and async connection plugins first, then async inventory plugins and async processors. If you do not opt in, nothing changes for you.

Long-running task execution. Today Nornir returns results only when every host has finished. That works for show version. It does not work for a software upgrade, an image copy or a commit-confirm. We propose streaming progress, per-host and per-run timeouts, cancellation, and detached runs that you can check on later, all opt-in, and all defined at the runner level.

Multi-vendor task ergonomics. Running one logical action across a mixed fleet still means writing platform dispatch by hand, and learning the inputs of each task by reading its source. We propose a typed contract for vendor-agnostic operations, with per-vendor implementations that anyone can write and publish.

Better documentation. Better search, a modern site, a real plugin catalogue, and a clearer path through the content. We also want your input on a bigger question: the ~30 plugin documentation sites of the ecosystem live on separate domains today. Is one shared entry point worth building, or is a good catalogue enough?

Native support for AI coding agents. People already use AI coding agents on Nornir, and the results depend too much on luck. We want to set the repository up so that this works well: one shared file with the project knowledge agents need (AGENTS.md), the standing rules of the project written down and checkable, and a simple workflow to plan large changes before writing code. Most of this is knowledge that today lives only in the heads of the maintainers; writing it down helps human contributors just as much. Nothing changes in the released package, and nobody has to use AI tools to contribute.

Preparing for a more distributed architecture. Nothing distributed ships in this roadmap. But streaming, cancellation and detached execution are specified as runner-level contracts on purpose, so that out-of-process and distributed backends can arrive later as plugins, without changing the core again.

The proposals

Each proposal is its own issue. Comment where you have an opinion; you do not need to read all seven.

#	Proposal	In short
#1085	Async Runner	An opt-in asyncio runner, await nr.arun(), and an optional async connection plugin protocol
#1086	Runner Enhancements	Streaming progress, timeouts, cancellation and detached runs, defined at the runner level
#1087	Async Inventory	An optional async inventory plugin protocol and await AInitNornir()
#1090	Async Processors	An optional async processor protocol, so that processors can await without blocking an async run
#1089	Operations: typed, multi-vendor actions	A typed, vendor-agnostic contract with per-vendor task implementations, and nr.run_operation()
#1088	Documentation refresh and plugin catalogue	What we will do on the docs, and a question about the ecosystem's ~30 plugin sites
#1084	Setting up the repository for AI coding agents	AGENTS.md, a shared .agents/ directory, and spec-kit for planning large changes

The proposals depend on each other in a few places: #1086 builds on #1085, and #1089 builds on #1086. Each issue says explicitly what it depends on.

What does not change

Every change in these proposals is additive. No existing public signature, protocol member, default value or entry-point name is modified. The test we hold ourselves to is simple: the complete existing test suite passes without modification, and upgrading requires zero code changes. That is also why the release carrying this work will most likely be 3.7, not 4.0: the existing interfaces do not change, and nobody should need a migration guide for changes that break nothing.

Process and timeline

Design discussion: the next 4 to 6 weeks. The proposal issues are open for comments, objections and alternatives. Every proposal lists its open questions explicitly; that is where your input helps most.

Alpha releases: in parallel. We will publish alpha releases along the way with whatever is already implemented, so that you can test the real behaviour and feed that back into the design. Some of this work already exists as working prototypes with passing test suites.

Beta: once the API is agreed. After the discussion converges, we move to a beta phase. Changes should then be minimal, unless a real problem is found.

Release. If the beta holds, a stable release follows about 4 to 6 weeks later.

How to take part

Comment on the proposal issues. Direct feedback is more useful to us than polite feedback. Test the alphas when they appear and tell us what breaks or feels wrong. And if you think a proposal solves the wrong problem entirely, we would rather hear it now than after the code lands.

Questions and disagreement are welcome.