Nornir makes it easy to run tasks across multiple network devices at once, whether you’re collecting information, updating configurations, or upgrading software. For simple tasks, this works well. But for longer operations, waiting until every device has finished before seeing the results can be a problem.
A software upgrade or configuration change can take several minutes per device. With Nornir 3.6, you can’t track progress as the tasks run or stop the operation if something goes wrong. And if a device becomes unresponsive, it can hold up the entire run.
Some teams also use Nornir within applications that run asynchronous code, such as FastAPI services, chatbots, or test suites. Because InitNornir and nr.run() are synchronous, they block the application’s event loop until they finish.
Nornir 3.7.0a1, the first pre-release of Nornir 3.7, addresses these limitations with three opt-in features from the 2026 Nornir roadmap:
- Follow the progress of a run, cancel it, and give each host a deadline. This works with the runner and the synchronous tasks you use today.
- Run
async deftasks on your application’s event loop with the newAsyncioRunner. - Load the inventory from an async application with
AInitNornir.
Existing scripts keep working and ThreadedRunner is still the default runner. Because this is an alpha, the new APIs can still change before 3.7.0, and we want your input on them before they do.
Follow, cancel, and time-limit runs with your current runner
These features don’t require any async code. They work with ThreadedRunner and, for following a run, with SerialRunner.
A task reports progress by yielding PartialResult objects. Its return value is still its final result. nr.stream() runs the task and gives you each event as it happens, so you can print or log the progress of every host during an upgrade:
import time from nornir import InitNornir from nornir.core.task import PartialResult, Result, Task nr = InitNornir(config_file="config.yaml") def upgrade(task: Task, image: str): yield PartialResult(host=task.host, result=f"copying {image}", progress=0.3) time.sleep(0.01) # replace with the image copy yield PartialResult(host=task.host, result="rebooting", progress=0.8) time.sleep(0.01) # replace with the reboot return Result(host=task.host, result=f"running {image}", changed=True) for event in nr.stream(task=upgrade, image="eos-4.32.bin"): if isinstance(event, PartialResult): print(f"{event.host.name}: {event.result} ({event.progress:.0%})") else: print(f"{event.host.name}: done, {event.result}")
If you prefer to keep nr.run(), a processor receives the same partial results through the new optional task_instance_progress hook, so you can build a progress bar in a processor.
nr.submit() starts a run in the background and returns a handle at once. handle.results() gives you the final result of each host in the order the hosts finish, and handle.cancel() stops the run. For example, you can stop a change on the remaining devices as soon as one device rejects it:
def change(task: Task): for _ in range(20): task.checkpoint() # a cancellation or a deadline stops the task here time.sleep(0.05) # replace with one step of the change if task.host.name == "edge-2": raise ValueError("the new configuration was rejected") return Result(host=task.host, result="change applied", changed=True) handle = nr.submit(task=change) for res in handle.results(): if res.failed: handle.cancel() break result = handle.result() # the usual AggregatedResult
To limit how long a run takes, set per_host_timeout for each host and timeout for the whole run, in seconds. You set them on the runner, under runner.options in the configuration file, or for a single run with run_options. A host that passes its deadline fails with TaskTimeoutError. The other hosts continue.
Every host ends a run with exactly one final result. A cancelled host carries TaskCancelledError and a timed-out host carries TaskTimeoutError. Both subclass BaseException, like asyncio.CancelledError, so an except Exception block in your task doesn’t hide a cancellation.
How a running task stops
On ThreadedRunner and SerialRunner, a task stops at its next checkpoint. A checkpoint is a call to task.checkpoint(), a yield, or the start of a subtask. If your task sends several commands with a blocking library such as Netmiko, call task.checkpoint() between the commands.
Nornir raises the cancellation or timeout once per host, at the first checkpoint. A cleanup subtask in a finally block still runs, so a task can release a configuration lock after it times out. When a subtask finishes during an interruption, Nornir keeps its result, because that subtask made its change on the device.
ThreadedRunner enforces a deadline even when a task is blocked in a call that never returns. The run records the host as timed out and returns on time. The blocked thread keeps its worker slot until the call returns.
What each runner supports:
| Runner | Follow a run | Run in the background | Where a cancellation or a deadline stops a task |
|---|---|---|---|
ThreadedRunner (default) |
stream |
submit |
at the next checkpoint |
SerialRunner |
stream |
not supported | at the next checkpoint |
AsyncioRunner |
astream |
asubmit |
at the call the task is awaiting |
The how-to guide on long-running tasks walks through each of these with examples you can run without devices.
Run async tasks on your application’s event loop
Nornir 3.6 runs every task in a thread. A plugin that uses an async library, such as scrapli with asyncssh, has to run one event loop in each worker thread. In 3.7.0a1, you select the asyncio runner and run async def tasks with await nr.arun(...). The runner executes them on your application’s event loop, and num_workers sets how many hosts run at the same time.
import asyncio from nornir import AInitNornir from nornir.core.task import Result, Task from nornir.plugins.runners import AsyncioRunner async def hello(task: Task) -> Result: await asyncio.sleep(0.1) # replace with an awaited call to the device or an API return Result(host=task.host, result=f"hello from {task.host.name}") async def main() -> None: nr = await AInitNornir(config_file="config.yaml") nr = nr.with_runner(AsyncioRunner(num_workers=10)) async with nr: results = await nr.arun(task=hello) for name, r in results.items(): print(name, r[0].result) asyncio.run(main())
async with nr closes the connections of every host when the block ends. You can also select the runner in the configuration file with runner.plugin: asyncio.
Connection plugins can now declare that they support synchronous use, asyncio, or both. Nornir binds an open connection to the mode that opened it. If a synchronous task tries to use a connection that an async task opened, Nornir raises ConnectionModeMismatchError.
Nornir also reports a mix-up between sync and async code as an error. In 3.6, nr.run() with an async def task didn’t run the task but reported the host as successful. In 3.7.0a1, it raises AsyncTaskOnSyncRunError, with a message that tells you to use await nr.arun(...).
Processor hooks stay synchronous in this release. They run on the event loop so a slow hook pauses every running task until it returns.
Read the how-to guide on the asyncio runner for details.
Load the inventory without blocking the event loop
AInitNornir is the async counterpart of InitNornir. nr = await AInitNornir(...) takes the same arguments and returns the same Nornir object, and your application keeps serving other requests while the inventory loads.
Your current inventory plugin works with it. AInitNornir runs a synchronous plugin in a worker thread. A plugin that must run in the main thread—for example, to install a signal handler—doesn’t work with AInitNornir. Keep InitNornir for that plugin.
For plugin authors, 3.7.0a1 adds an inventory plugin contract for plugins that load synchronously, asynchronously, or both. Inventory sources with an HTTP or GraphQL API, such as Infrahub, can then load hosts with an async client. Transform functions can also be async def now. AInitNornir awaits them once per host.
Read the how-to guide on loading the inventory from an async application, and the guides on writing connection plugins and inventory plugins that support both modes.
Test async tasks against real devices and Infrahub
Most plugins don’t use the new APIs yet. Two plugins have pre-releases that do. Use them to test 3.7.0a1 against real systems. If you write plugins, they show what adding async support looks like in practice.
nornir-scrapli 1.6.0a1 adds async versions of the Scrapli CLI and Scrapli-Cfg tasks in nornir_scrapli.async_tasks, such as send_command, send_configs, cfg_diff_config and cfg_commit_config. They take the same arguments and return the same results as the synchronous tasks.
The scrapli and scrapli_cfg connections support both modes under the same names and with the same inventory. When transport isn’t set, a connection opened from an async task uses asyncssh. NETCONF tasks remain synchronous.
pip install "nornir-scrapli[asyncio]==1.6.0a1"
nornir-infrahub 1.3.0a2 loads the Infrahub inventory with await AInitNornir(...), using the async Infrahub client. The InfrahubInventory plugin keeps its name and works with both InitNornir and AInitNornir. The release also adds async versions of the artifact and file object tasks, such as aget_artifact and agenerate_artifacts.
pip install "nornir-infrahub==1.3.0a2"
Both pre-releases require Nornir 3.7.0a1.
Before you install the pre-release
pip install --upgrade nornir doesn’t install a pre-release. Give the version explicitly, preferably in a separate virtual environment:
pip install "nornir==3.7.0a1"
Don’t use 3.7.0a1 in production.
The existing plugin contracts didn’t change. Four behaviors did change. Check whether your code depends on one of them:
Nornir.runandTask.runraiseAsyncTaskOnSyncRunErrorfor anasync deftask. Before, the task didn’t run but the host was reported as successful.- A task that contains
yieldnow runs as a progress-reporting task. Before, its body never ran but the host was reported as successful. InitNornirraisesTransformFunctionNotSyncErrorfor a transform function defined withasync def. Before, the transform function didn’t run.Host.close_connectionstries to close every connection, then raises the first error. Before, it stopped at the first connection that it couldn’t close.
Tell us what works and what doesn’t
We can change the new APIs before 3.7.0 based on what you report. The feedback we need most:
- Do your existing scripts and plugins still produce the same results with 3.7.0a1 as with 3.6.1? This is the most useful test.
- Do
stream,submitand the per-host deadlines fit the way you run long operations, such as upgrades, image copies, and commit-confirms? - Can you add
task.checkpoint()calls to tasks built on the libraries you use, or do you need a different way to stop a task? - If you maintain a connection or inventory plugin, can you add async support with the new plugin contracts?
To give feedback:
- Comment on the issue of the feature: #1085 Async Runner, #1086 Runner Enhancements or #1087 Async Inventory.
- Open a new issue for a bug. Include the steps to reproduce it, and your Nornir and Python versions.
- Write in the
#nornirchannel of the OpsMill Discord server or networktocode Slack team.
Get Nornir 3.7.0a1
Nornir 3.7.0a1 lets you follow, stop, and time-limit runs with the runner you already use, and run Nornir on an asyncio event loop with async tasks, connections, and inventories.