Nornir Release 3.7.0a1 Brings Async Tasks, Cancellable Runs, and Timeouts

|

Nov 16, 2026

In this post

Category

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 def tasks on your application’s event loop with the new AsyncioRunner.
  • 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:

  1. Nornir.run and Task.run raise AsyncTaskOnSyncRunError for an async def task. Before, the task didn’t run but the host was reported as successful.
  2. A task that contains yield now runs as a progress-reporting task. Before, its body never ran but the host was reported as successful.
  3. InitNornir raises TransformFunctionNotSyncError for a transform function defined with async def. Before, the transform function didn’t run.
  4. Host.close_connections tries 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, submit and 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:

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.

Wim Van Deun, OpsMill Product Manager

Wim Van Deun | Network and security engineer deep at heart, with automation creds dating back to when Perl and crontab ruled the land. Brings quiet intensity and strategic execution as OpsMill’s Product Manager. Hardcore trail runner based in Belgium.

REQUEST A DEMO

Infrahub by OpsMill logo

See what Infrahub can do for you

✔ Get a personal tour of Infrahub Enterprise

✔ Learn how we can support your infrastructure automation goals

✔ Ask questions and get advice from our automation experts

By submitting this form, I confirm that I have read and agree to OpsMill’s privacy policy.

Fantastic! 🙌

Check your email for a message from our team.

From there, you can pick a demo time that’s convenient for you and invite any colleagues who you want to attend.

We’re looking forward to hearing about your automation goals and exploring how Infrahub can help you meet them.

Get Ottermatic

Join hundreds of your industry peers exploring trends, tips, and talk in infrastructure automation.

Activate your subscription.

blue OpsMill otter