Nornir guide

Nornir Network Automation: Inventory, Tasks and Python Examples

How Nornir runs your own Python tasks across a device inventory, which plugins connect it to devices, worked examples, and what to plan for before production.

What Nornir is and who it suits

Nornir network automation means running your own Python tasks across an inventory of devices. Nornir is an open source, pure Python framework with inventory management and multi-threaded task execution, used directly from Python rather than through a domain-specific language. It supplies three things around a task: a record of which devices exist and how to reach them, a runner that executes the task on many of them at once, and a structured result for each host. The task itself stays yours.

Nornir does not talk to devices itself. Connection plugins such as Netmiko, NAPALM and Scrapli do that. A task asks its host for a named connection, Nornir opens it through the matching plugin the first time it is needed, and later tasks on the same host reuse it. The framework suits teams that are comfortable in Python and want full control of the logic, with automation they can step through in a debugger, cover with unit tests and extend with any Python library. It is a framework to build with, not a finished application.

Latest release
3.6.0, released 2 August 2026 (release page on PyPI)
Licence
Apache-2.0
Python
3.10 or newer. PyPI lists Python 3.10 to 3.14
Maintenance
Created by David Barroso. OpsMill is now the steward, and nornir.tech states that Nornir will remain open source and community-driven, and that David Barroso continues to support it as a Technical Advisor (OpsMill's announcement)

Verified on . Release and plugin details were checked against PyPI and nornir.tech, and behaviour against the Nornir 3.6.0 documentation and source. Every example was written for Nornir 3.6.0 and checked against that source. The local inventory examples, with plain Python tasks that open no device connection, were run on a stub inventory of documentation addresses. None of the examples was run against a network device, so run them against a lab before production.

How Nornir runs network automation tasks

Nornir has a small number of moving parts. Once you can name them, the documentation and the plugins are much easier to read. The official tutorial walks through the same ideas with a larger example.

How Nornir connects inventory, runner, tasks, connection plugins, devices and resultsA column of five steps, top to bottom. The inventory lists the hosts, groups and defaults. The runner starts your task on each selected host using a pool of worker threads. The task is a Python function, or a task that a plugin provides. The task asks for a connection plugin such as Netmiko, NAPALM or Scrapli, and the plugin talks to the network device. A separate box on the right, Results, receives one result per host from the tasks. The runner gathers them and returns them to your script.InventoryHosts, groups, defaultsselects hostsRunnerWorker threads, one task per hostruns your taskTasksYour functions and plugin tasksasks for a connectionConnection pluginsNetmiko, NAPALM, ScrapliSSH or APINetwork devicesSwitches, routers, firewallsResultsOne per hostgatheredby runner
The inventory says which hosts exist, the runner executes your task on them, and connection plugins do the talking to each device. Each task returns a result, and the runner gathers them for your script.

Tasks and subtasks

A task is a Python function whose first argument is a Task and which returns a Result. Plugins ship ready-made tasks, and you write your own for anything else. A task can call task.run to run other tasks as subtasks on the same host, which is how you group several steps into one unit of work.

The runner and num_workers

The runner decides how a task is executed across the hosts. The default is the threaded runner, which runs the task for each host on a pool of threads sized by num_workers. In the 3.6.0 source the default is 20, and the configuration example in the documentation also sets 20. A serial runner is also included, which runs one host at a time. You set the runner in config.yaml, in code, or with the NORNIR_RUNNER_OPTIONS environment variable, and the configuration reference gives the order of precedence: code, then the configuration file, then the environment.

Set the number of worker threads in code
from nornir import InitNornir

# Code takes precedence over config.yaml, which takes precedence over
# the NORNIR_RUNNER_OPTIONS environment variable.
nr = InitNornir(
    config_file="config.yaml",
    runner={"plugin": "threaded", "options": {"num_workers": 5}},
)

Results and processors

nr.run() returns an AggregatedResult, which behaves like a dictionary from host name to a MultiResult. A MultiResult is a list of Result objects: the first is the task itself and any subtasks follow it. Each Result carries result, changed, diff, failed and any exception.

Read an AggregatedResult: host, then MultiResult, then Result
results = nr.run(task=describe_host)

print(results.failed)  # True if any host failed

for host_name, multi_result in results.items():
    first = multi_result[0]  # the task itself; subtasks follow
    print(host_name, first.failed, first.result)

Processors are the alternative: plugins that run code on events such as a task starting, a host finishing or a subtask completing. Their advantage is that you handle each host as soon as it completes, without waiting for the rest.

A processor that reports progress as each host finishes
from nornir import InitNornir
from nornir.core.inventory import Host
from nornir.core.task import AggregatedResult, MultiResult, Task


class ProgressPrinter:
    def task_started(self, task: Task) -> None:
        print(f"started: {task.name}")

    def task_completed(self, task: Task, result: AggregatedResult) -> None:
        print(f"completed: {task.name}")

    def task_instance_started(self, task: Task, host: Host) -> None:
        pass

    def task_instance_completed(
        self, task: Task, host: Host, result: MultiResult
    ) -> None:
        state = "failed" if result.failed else "ok"
        print(f"  {host.name}: {state}")

    def subtask_instance_started(self, task: Task, host: Host) -> None:
        pass

    def subtask_instance_completed(
        self, task: Task, host: Host, result: MultiResult
    ) -> None:
        pass


nr = InitNornir(config_file="config.yaml").with_processors([ProgressPrinter()])

Nornir inventory: hosts, groups and defaults

The inventory is made of hosts, groups and defaults. The default inventory plugin, SimpleInventory, reads them from three YAML files. A host holds its own settings and lists the groups it belongs to. A value set on the host wins over the same value on its groups, and group values win over defaults. If more than one group sets a value, the group listed first on the host wins. Free-form values go under data, and any task can read them from task.host. The files below are the inventory used by the examples in the rest of this guide. They use documentation addresses (192.0.2.0/24 and 198.51.100.0/24), and the platform on each host comes from its group.

inventory/hosts.yaml: one entry per device
---
edge-sw01:
  hostname: 192.0.2.11
  groups:
    - ios
    - dc1
  data:
    role: access

edge-sw02:
  hostname: 192.0.2.12
  groups:
    - ios
    - dc1
  data:
    role: access

core-rtr01:
  hostname: 198.51.100.21
  groups:
    - junos
    - dc2
  data:
    role: core
inventory/groups.yaml and defaults.yaml: shared settings
# inventory/groups.yaml
---
ios:
  platform: ios

junos:
  platform: junos

dc1:
  data:
    site: dc1

dc2:
  data:
    site: dc2

# inventory/defaults.yaml
---
port: 22

Filtering the inventory

nr.filter() returns a new Nornir object that holds only the matching hosts, so you can run a task on part of the inventory. Keyword arguments match attributes or data values, and F objects add lookups such as __contains__, __in, __any and __all, combined with &, | and ~.

Filter the inventory with keyword arguments and F objects
from nornir import InitNornir
from nornir.core.filter import F

nr = InitNornir(config_file="config.yaml")

ios_hosts = nr.filter(platform="ios")
dc1_hosts = nr.filter(F(groups__contains="dc1"))
dc1_access = nr.filter(F(groups__contains="dc1") & F(role="access"))
not_junos = nr.filter(~F(platform="junos"))

print(list(dc1_access.inventory.hosts))
print(len(not_junos.inventory.hosts))

Install Nornir and run your first Python task

Nornir 3.6.0 needs Python 3.10 or newer. Install it into a virtual environment with pip, together with the plugins you will use. Nornir finds installed plugins by itself when you create the Nornir object.

Install Nornir and the plugins this guide uses
python3 -m venv .venv
source .venv/bin/activate
pip install nornir nornir-utils nornir-netmiko nornir-napalm

Take credentials from environment variables instead of writing them into the inventory files. The load_credentials transform function in nornir_utils reads NORNIR_USERNAME and NORNIR_PASSWORD and sets them on every host. config.yaml names that function and tells Nornir where the inventory files are, how to run and how to log.

Set device credentials in the environment, never in the YAML
# Set these in your shell, or load them from a secret store.
# Never commit them to a repository.
export NORNIR_USERNAME="netops"
export NORNIR_PASSWORD="replace-with-your-password"
config.yaml: where the inventory lives, how to run, how to log
---
inventory:
  plugin: SimpleInventory
  options:
    host_file: "inventory/hosts.yaml"
    group_file: "inventory/groups.yaml"
    defaults_file: "inventory/defaults.yaml"
  # Reads NORNIR_USERNAME and NORNIR_PASSWORD from the environment
  # and sets them on every host.
  transform_function: load_credentials
runner:
  plugin: threaded
  options:
    num_workers: 10
logging:
  level: INFO
  log_file: nornir.log

The first task below reads only the inventory, so it needs no device. If it prints one result per host, the inventory loads and the runner can execute a local task. Use it as a smoke test before you add a connection plugin.

A first task that needs no device, to prove the inventory loads
from nornir import InitNornir
from nornir.core.task import Result, Task
from nornir_utils.plugins.functions import print_result


def describe_host(task: Task) -> Result:
    role = task.host.get("role", "unknown")
    return Result(
        host=task.host,
        result=f"{task.host.name} ({task.host.hostname}) has role {role}",
    )


nr = InitNornir(config_file="config.yaml")
results = nr.run(task=describe_host)
print_result(results)
Local example output: python first_run.py on the inventory above, Nornir 3.6.0, no device contacted
$ python first_run.py
describe_host*******************************************************************
* core-rtr01 ** changed : False ************************************************
vvvv describe_host ** changed : False vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv INFO
core-rtr01 (198.51.100.21) has role core
^^^^ END describe_host ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* edge-sw01 ** changed : False *************************************************
vvvv describe_host ** changed : False vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv INFO
edge-sw01 (192.0.2.11) has role access
^^^^ END describe_host ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* edge-sw02 ** changed : False *************************************************
vvvv describe_host ** changed : False vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv INFO
edge-sw02 (192.0.2.12) has role access
^^^^ END describe_host ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This output was captured from a real local run on 4 October 2026, with only the terminal colour codes removed (the panel keeps the colours print_result used). The hostnames are documentation addresses. The hosts can appear in a different order on each run, because the threaded runner reports whichever host finishes first.

The first task does not prove that credentials are set. This one checks that each host has a username and a password, without printing either, and marks the host as failed if one is missing.

Check that credentials are present without printing them
from nornir.core.task import Result, Task


def check_credentials(task: Task) -> Result:
    present = bool(task.host.username) and bool(task.host.password)
    return Result(
        host=task.host,
        result=f"credentials present: {present}",
        failed=not present,
    )


results = nr.run(task=check_credentials)
print(results.failed)  # True if any host has no username or password

Nornir plugins for Netmiko, NAPALM and Scrapli

Nornir itself is small. Almost everything that touches a device or an outside system is a plugin: connection plugins, tasks, inventory sources, processors and runners. A plugin is an ordinary Python package. When you create the Nornir object, Nornir registers the plugins it finds installed, so you reference them by name in the configuration or import their tasks. The documentation keeps a community plugin list, with each plugin's type and maintainers. Plugins are separate projects with their own maintainers and release schedules, so check the release date and Python support of each one before you rely on it. The table shows the five used in this guide, as listed on PyPI on the verification date. PyPI treats hyphens and underscores in project names as the same, so pip install nornir-napalm and pip install nornir_napalm install the same package, while in Python you import the underscore form, for example nornir_napalm.

Nornir plugins used in this guide, with PyPI package name, release and author
PyPI packageProvidesLatest release on PyPIAuthor on PyPI
nornir-netmikoNetmiko connection plugin and tasks1.0.1, 7 December 2023Kirk Byers
nornir_napalmNAPALM connection plugin and tasks0.6.0, 3 August 2026David Barroso
nornir-scrapliScrapli connection plugins and tasks2025.1.30, 31 January 2025Carl Montanari
nornir-utilsprint_result, YAMLInventory, load_credentials, write_file and other helpers with no external dependencies0.3.0, 3 August 2026David Barroso
nornir_jinja2Tasks that render Jinja2 templates1.0.0, 3 August 2026David Barroso

Netmiko: nornir_netmiko

The Netmiko plugin runs Netmiko sessions inside Nornir tasks. Netmiko handles prompts, paging and configuration modes for each device, and Nornir runs the work across your inventory. Its tasks include netmiko_send_command, netmiko_send_config, netmiko_save_config and netmiko_file_transfer. For the Netmiko library itself, read the Netmiko guide.

Nornir opens a connection the first time a task needs one and keeps it for later tasks on the same host. Using the Nornir object as a context manager closes the connections for every host when the block ends, failed hosts included, which is why the complete device examples in this guide use with InitNornir(...) as nr.

nornir_netmiko: run a show command on every IOS host
from nornir import InitNornir
from nornir_netmiko.tasks import netmiko_send_command
from nornir_utils.plugins.functions import print_result

# Leaving the with block closes the connections for every host,
# including hosts that failed.
with InitNornir(config_file="config.yaml") as nr:
    ios_hosts = nr.filter(platform="ios")
    results = ios_hosts.run(
        task=netmiko_send_command,
        command_string="show version",
    )
    print_result(results)

To group several plugin tasks into one unit of work, call them from your own task with task.run.

Group plugin tasks into your own task with task.run
from nornir.core.task import Result, Task
from nornir_netmiko.tasks import netmiko_send_command


def count_config_lines(task: Task) -> Result:
    output = task.run(
        task=netmiko_send_command,
        command_string="show running-config",
    )
    lines = len(output.result.splitlines())
    return Result(host=task.host, result=f"{lines} lines of configuration")


# Run inside the same with block as the example above.
results = ios_hosts.run(task=count_config_lines)

NAPALM: nornir_napalm

The NAPALM plugin gives you NAPALM's getters and its configuration merge and replace, run across the inventory. napalm_get returns structured data, napalm_cli sends raw commands, and napalm_configure loads configuration and supports dry_run to preview the diff first. NAPALM gives you a common API, but the configuration text you load must still match the platform of the target device, so select hosts by platform when you push a file or a rendered template.

nornir_napalm: read structured facts through NAPALM getters
from nornir import InitNornir
from nornir_napalm.plugins.tasks import napalm_get
from nornir_utils.plugins.functions import print_result

with InitNornir(config_file="config.yaml") as nr:
    results = nr.run(task=napalm_get, getters=["facts"])
    print_result(results)

    for host_name, multi_result in results.items():
        if not multi_result.failed:
            print(host_name, multi_result[0].result["facts"]["os_version"])

A dry run is not offline, and it is not the same as rendering a template locally. In the installed nornir_napalm 0.6.0 source, napalm_configure opens a session to the device, loads the configuration as a candidate to compute the diff, and then discards the candidate when dry_run is true. Nothing is committed, but the device is contacted. The file below is the change loaded by the example, in Cisco IOS syntax to match the hosts it selects.

changes/ntp.cfg (Cisco IOS syntax, matching the ios hosts selected above)
ntp server 198.51.100.123
nornir_napalm: preview a change with dry_run before applying it
from nornir import InitNornir
from nornir_napalm.plugins.tasks import napalm_configure
from nornir_utils.plugins.functions import print_result

with InitNornir(config_file="config.yaml") as nr:
    ios_hosts = nr.filter(platform="ios")

    # dry_run=True still opens a session and loads the file as a candidate
    # configuration to compute the diff, then discards the candidate.
    preview = ios_hosts.run(
        task=napalm_configure,
        filename="changes/ntp.cfg",
        dry_run=True,
    )
    print_result(preview)  # print_result shows each host's diff

Scrapli: nornir_scrapli

The Scrapli plugin offers the same pattern with Scrapli as the connection library, and also provides plugins for Scrapli's configuration and NETCONF drivers. In the installed 2025.1.30 source the platform names ios, nxos, iosxr, eos and junos are mapped to their Scrapli names. Install it with its own package. On 4 October 2026, nornir-scrapli 2025.1.30 imported cleanly with scrapli 2025.1.30 and failed on import with scrapli 2026.10.3, so the install line below pins the former. Only the import was checked.

Install the Scrapli plugin with the scrapli release it was checked against
pip install nornir-scrapli "scrapli==2025.1.30"
nornir_scrapli: the same pattern with the Scrapli plugin
from nornir import InitNornir
from nornir_scrapli.tasks import send_command
from nornir_utils.plugins.functions import print_result

with InitNornir(config_file="config.yaml") as nr:
    results = nr.filter(platform="ios").run(
        task=send_command,
        command="show version",
    )
    print_result(results)

Helpers and templates: nornir_utils and nornir_jinja2

nornir_utils is the helper package most scripts install first. It provides print_result and print_title for readable output, the load_credentials transform function used above, an alternative YAMLInventory, and tasks such as write_file, echo_data, load_yaml and tcp_ping.

nornir_utils: print one attribute, then only the hosts that failed
from nornir_utils.plugins.functions import print_result, print_title

print_title("Show version")
print_result(results, vars=["result"])  # skip diff and stdout

print_title("Hosts that failed")
for multi_result in results.failed_hosts.values():
    print_result(multi_result)

nornir_jinja2 provides template_file and a companion string task, so a per-host configuration can be rendered from a template and the host's inventory data. Install it with its own package.

Install the Jinja2 plugin
pip install nornir_jinja2

Rendering is local and never touches the device. Pair it with napalm_configure and dry_run=True to review the result: that step does contact the device, as described above. The template below uses Cisco IOS syntax, so the example runs it only on hosts whose platform is ios. A Junos host would need its own template, selected by host.platform.

templates/ntp.j2 (Cisco IOS syntax)
ntp server {{ ntp_server }}
nornir_jinja2: render a template per host, then preview with NAPALM
from nornir import InitNornir
from nornir.core.task import Result, Task
from nornir_jinja2.plugins.tasks import template_file
from nornir_napalm.plugins.tasks import napalm_configure
from nornir_utils.plugins.functions import print_result


def render_and_preview(task: Task) -> Result:
    # templates/ntp.j2 uses Cisco IOS syntax, so only run it on ios hosts.
    rendered = task.run(
        task=template_file,
        template="ntp.j2",
        path="templates",
        ntp_server="198.51.100.123",
    )
    task.run(
        task=napalm_configure,
        configuration=rendered.result,
        dry_run=True,
    )
    return Result(host=task.host, result="previewed, nothing committed")


with InitNornir(config_file="config.yaml") as nr:
    ios_hosts = nr.filter(platform="ios")
    print_result(ios_hosts.run(task=render_and_preview))

Platform names across plugins

One inventory platform value can serve several plugins. In the installed source, the Netmiko plugin translates NAPALM-style names (ios, nxos, nxos_ssh, eos, junos, iosxr) to Netmiko device types such as cisco_ios and juniper_junos, and the Scrapli plugin does the same for its own names. Any other value is passed through unchanged, so use the library's own name for platforms outside those maps.

Dynamic Nornir inventory with NetBox and Infrahub

Version-controlled YAML inventories suit production as well as labs, and many teams keep them that way. Dynamic inventory becomes useful when another system already owns the device data: the YAML would then be a second copy to keep correct. An inventory plugin replaces it with a query to that system, so the Nornir inventory is built from it each time you run.

NetBox: nornir_netbox

nornir_netbox is the inventory plugin for NetBox. Use NetBoxInventory2, because in the installed 0.3.0 source the older NBInventory raises a deprecation warning pointing to it. filter_parameters passes NetBox API filters, so you can select devices by site, role or tag, and use_platform_napalm_driver takes each host's platform from the NetBox platform's NAPALM driver setting. The plugin reads NB_URL and NB_TOKEN if you do not pass them, and falls back to a local URL and a placeholder token when they are missing, so set both explicitly. The latest release on PyPI is dated 20 September 2021 and its author is Wim Van Deun, so try it against your NetBox version in a lab first.

Install the NetBox inventory plugin
pip install nornir-netbox
nornir_netbox: build the inventory from NetBox instead of YAML
import os

from nornir import InitNornir

nr = InitNornir(
    inventory={
        "plugin": "NetBoxInventory2",
        "options": {
            "nb_url": os.environ["NB_URL"],
            "nb_token": os.environ["NB_TOKEN"],
            "filter_parameters": {"site": "dc1"},
            "use_platform_napalm_driver": True,
        },
    },
)
print(len(nr.inventory.hosts))

Infrahub: nornir-infrahub

OpsMill, the steward of Nornir, also publishes nornir-infrahub, an inventory plugin for Infrahub, at version 1.2.0 on PyPI (30 July 2026, Apache-2.0). It maps an Infrahub node kind to Nornir hosts and can build groups from attributes or relations. The mappings name attributes in your own Infrahub schema, so the ones below are placeholders to replace with yours. OpsMill states that using Nornir does not require Infrahub.

Install the Infrahub inventory plugin
pip install nornir-infrahub
nornir-infrahub: build the inventory from Infrahub
import os

from nornir import InitNornir

nr = InitNornir(
    inventory={
        "plugin": "InfrahubInventory",
        "options": {
            "address": os.environ["INFRAHUB_ADDRESS"],
            "token": os.environ["INFRAHUB_API_TOKEN"],
            "host_node": {"kind": "InfraDevice"},
            "schema_mappings": [
                {"name": "hostname", "mapping": "primary_address.address"},
                {"name": "platform", "mapping": "platform.nornir_platform"},
            ],
            "group_mappings": ["site.name"],
        },
    },
)
print(list(nr.inventory.hosts))

Nornir vs Ansible for network automation

Both run the same kind of work across many devices, so the comparison comes up often. They differ mostly in how you write and review the automation, not in what network operations they can drive. Neither is the better tool in the abstract. Netmiko and NAPALM are not a third option: they are libraries that talk to devices, and Nornir drives them through the nornir_netmiko and nornir_napalm plugins. For the Netmiko library on its own, read the Netmiko guide.

Nornir and Ansible compared on authoring, inventory, concurrency, device connections and ecosystem
AspectNornirAnsible
How you write automationPython. Tasks are functions, run from a script you can step through in a debugger and cover with tests.Playbooks, which the documentation says you express in YAML format with a minimum of syntax. Ansible itself is written and executed in Python, and the network guide describes separating the data model (playbook or role) from the execution layer (modules). Source
InventoryHosts, groups and defaults, from YAML files with SimpleInventory or from an inventory plugin such as NetBox or Infrahub. A host value beats its groups, which beat the defaults.Composed from one or more inventory sources. INI and YAML are built in, inventory plugins support other formats and dynamic sources, and a group can have multiple parents and children. Source
ConcurrencyA pool of threads in one Python process, set by num_workers, which defaults to 20 in the 3.6.0 source. A serial runner is also included.Forks, which default to 5. The default linear strategy runs each task on all hosts in a play before starting the next task. The free strategy lets each host run to the end of the play as fast as it can, and the serial keyword runs a play in batches of hosts. Source
Talking to network devicesThrough connection plugins such as Netmiko, NAPALM and Scrapli, which you choose per task.Network modules run on the control node, and the ansible_connection variable selects the protocol: network_cli (CLI over SSH), netconf (XML over SSH) or httpapi (API over HTTP or HTTPS). Each needs the network_os setting. Source
EcosystemA community plugin list in the Nornir documentation, plus the whole Python ecosystem for anything else. SourceCollections organised by network platform, for example arista.eos, cisco.ios, cisco.nxos and junipernetworks.junos, published on Ansible Galaxy. Source

The Ansible column restates the Ansible documentation pages, read on 2 October 2026, and each cell links the page it comes from. The fork and strategy defaults were re-checked in Ansible's configuration schema on 4 October 2026. Defaults can change between releases, so check the forks setting and the strategies page for your version.

Choosing between them, or using both

Nornir tends to suit a team that is comfortable in Python and wants full control of the logic: branching on results, calling an API partway through a task, reusing a library, or writing unit tests for the automation. Ansible tends to suit a team that already runs it, or that prefers automation written as YAML playbooks that people who are not Python developers can read and review. Its network guide presents it as one agentless tool that network, operations and development teams can all use, and its platform collections cover a wide range of vendors. If your servers and network are automated in the same tool today, that is a real advantage.

They are not exclusive. Some teams use Ansible for the work that fits its model and Nornir where they need custom logic, and Nornir's community plugin list includes an inventory plugin that reads Ansible inventories, so one inventory can feed both.

Troubleshooting Nornir tasks and connections

Most first problems are one of five things: a host that failed and is now being skipped, connection settings that differ by platform, too many threads, silent logging, or an inventory that does not load. The behaviour below comes from the Nornir 3.6.0 documentation and source. The documentation covers more.

Failed hosts and the real exception

By default a task that raises an exception does not stop the run. Nornir records the failure in the result and adds the host to a set of failed hosts, and later calls to nr.run() skip those hosts unless you pass on_failed=True. Inspect results.failed and results.failed_hosts. Clear the list with nr.data.reset_failed_hosts(), or one host with nr.data.recover_host(name).

Set raise_on_error=True to raise NornirExecutionError after the run if any selected host failed. It does not cancel tasks already running on other hosts: in the 3.6.0 source the runner finishes every selected host first, and the error is raised afterwards. That matters for configuration changes, where other hosts may already have been changed by the time the error reaches you, so start with a small, filtered batch.

Where a task calls subtasks with task.run, a failure in a subtask stops the parent task at that point. The parent's own entry, multi_result[0], then carries a NornirSubTaskError, and the exception from the device sits in a later entry of the MultiResult. The Nornir tutorial on failed tasks shows the same thing. Loop over the entries and look at each one that failed, or pass the MultiResult to print_result() to see the underlying traceback. A task that raises directly, with no subtask, keeps its exception in entry zero.

Inspect every failed entry, retry failed hosts, and reset the failed list
from nornir import InitNornir
from nornir.core.exceptions import NornirExecutionError
from nornir.core.task import Result, Task


def flaky_step(task: Task) -> Result:
    if task.host.name == "edge-sw02":
        raise ConnectionError("simulated: device unreachable")
    return Result(host=task.host, result="ok")


def grouped(task: Task) -> Result:
    task.run(task=flaky_step)
    return Result(host=task.host, result="done")


nr = InitNornir(config_file="config.yaml")

results = nr.run(task=grouped)
for host_name, multi_result in results.failed_hosts.items():
    for entry in multi_result:
        if entry.failed:
            print(host_name, entry.name, repr(entry.exception))

# A failed host is skipped by later runs unless you ask for it.
again = nr.run(task=grouped)
print(sorted(again))  # edge-sw02 is not in here

retry = nr.run(task=grouped, on_failed=True, on_good=False)
print(sorted(retry))  # only edge-sw02

nr.data.reset_failed_hosts()  # every host is eligible again

# raise_on_error raises after the run, once every selected host has finished.
try:
    nr.run(task=grouped, raise_on_error=True)
except NornirExecutionError as error:
    print("raised:", sorted(error.failed_hosts))

netmiko_send_config also raises ValueError when the run is a dry run, because in the installed nornir_netmiko source it does not support dry runs. Use napalm_configure with dry_run=True when you want a preview.

Connection options per platform

Connection settings that work on one platform are often wrong on another: a slower device needs a longer timeout, a different OS needs a different driver name. Put them on the group, under connection_options, keyed by the connection plugin. The extras dictionary is passed to the underlying library, so for Netmiko it holds ConnectHandler arguments such as conn_timeout, and for NAPALM it holds driver arguments such as timeout. If a connection fails at once, also check the platform name: the Netmiko and Scrapli plugins translate only the names listed in the plugins section and pass the rest through.

Per-platform connection options in groups.yaml
---
ios:
  platform: ios
  connection_options:
    netmiko:
      extras:
        conn_timeout: 30   # passed to Netmiko's ConnectHandler
    napalm:
      extras:
        timeout: 120       # passed to the NAPALM driver

junos:
  platform: junos

Thread count and device rate limits

The threaded runner uses a thread pool of num_workers threads, and in the 3.6.0 source the default is 20. The threaded runner limits concurrency through num_workers, and any further pacing or retry behaviour depends on your workflow, so 20 simultaneous logins can be too many for a TACACS+ or RADIUS server, a jump host or an older device that limits concurrent sessions. If you see timeouts or login failures only on large runs, lower num_workers, or use the serial runner to confirm that concurrency is the cause. Raise it again gradually once the run is stable.

Logging

Nornir configures logging itself when you create the Nornir object. By default it writes INFO level messages to nornir.log in the working directory, rotating the file at 10 MB, and does not print to the console. If a task fails and the console shows nothing, read that file. Set level: DEBUG in the logging section for more detail, and to_console: true to see it live. If your application already configures Python logging, Nornir emits a ConflictingConfigurationWarning; set logging.enabled to false and let your own configuration take over.

Turn on debug logging, written to nornir.log
---
logging:
  level: DEBUG
  log_file: nornir.log
  to_console: false

Inventory loading errors

An inventory problem stops InitNornir before any task runs, which is the best place for it. The three common ones behave as follows. A missing file raises FileNotFoundError naming the path, so check the paths in config.yaml against the directory you run from. Invalid YAML raises a parser error from the YAML library, with the line of the problem. A host that lists a group missing from groups.yaml raises a KeyError naming that group. After a change to the inventory, a short script that loads it and prints the hosts, groups and whether credentials are set is a quick check.

Check the inventory loads before running anything
from nornir import InitNornir

nr = InitNornir(config_file="config.yaml")

print(len(nr.inventory.hosts), "hosts")
print(sorted(nr.inventory.groups))
for name, host in nr.inventory.hosts.items():
    print(name, host.hostname, host.platform, host.username is not None)

Production considerations for Nornir

Nornir is a framework, and it is deliberately scoped as one: it runs your tasks across an inventory and reports the results. Running automation across a whole estate means providing, integrating or maintaining several capabilities around it. Many organisations already have some of them, so the work is often integration, not building from scratch. The table is a set of requirements to check, not a build plan, and which rows apply depends on your estate, your auditors and your team. None of it is a flaw in Nornir.

Requirements for running Nornir in production, why each matters and how teams can provide it
RequirementWhy it mattersHow teams can provide it
Inventory and a source of truthNornir needs to know which devices exist, their platforms and their addresses, and somebody has to keep that correct as devices are added, moved and retired.Version-controlled YAML inventories suit production. Use a dynamic inventory plugin when another system, such as NetBox or Infrahub, already owns the data.
Concurrency and rate limitingMany simultaneous logins can overload AAA servers, jump hosts and devices that limit concurrent sessions.Set num_workers deliberately, or use the serial runner while testing. Further pacing and retry behaviour is part of your own workflow.
Scheduling and run visibilityRegular collection needs something to start it, retries for unreachable devices, and a way to see that a run finished.Cron, a CI system or an orchestrator can start the runs. Retries and run reporting are yours to add.
Configuration versioning and diffCollecting a configuration is one step. Teams also need each version kept with its device and time, and a diff that ignores noise such as timestamps.A Git repository, an existing archive or a dedicated tool. Filtering the noise out of the diff is the part that takes work.
Compliance checksChecking configurations against policy means defined rules, a run on each collection and a result per device and per rule that an auditor can repeat.Write the rules and the reporting yourself, or evaluate a tool that supplies them.
Access control and sign-in for peopleOnce more than one person uses the automation, someone has to decide who may run which task against which devices, and people will expect to sign in through the identity provider or RADIUS server you already run. This is separate from how the automation signs in to devices.Permissions you already have in a CI system or on a jump host can cover part of it. A service that people use needs its own sign-in integration.
Device credentials and rotationEnvironment variables are the right start. At scale you need accounts scoped per device or group, and rotation that does not break scheduled jobs.A secret store read at run time, with per-group accounts and a tested rotation procedure.
Audit trailAuditors may ask who ran what, against which device, and with what result, for as long as you must keep the evidence.Existing logging, CI job history or a SIEM may already capture part of it. Check that retention matches the requirement.
High availabilityIf runs start from one host, that host becomes part of the operations process.Run the automation on a platform that already provides resilient scheduled jobs.
Ownership of plugin and driver breakagePlugins are separate projects with their own release schedules, and the libraries beneath them follow vendor changes. A prompt, a banner or a command output can change between OS releases. A new release of a dependency can break a plugin, as the Scrapli note above shows.Pin versions, test against each new OS release in a lab, and name an owner who decides when a plugin needs replacing.

Using Nornir alongside rConfig

“Alongside” means the two can coexist. Your custom Python workflows can keep using Nornir, while rConfig can take on some of the configuration management requirements in the production table above. This guide does not describe a native integration between them, and rConfig does not claim to match Nornir for scripted change or automation. Custom workflows, bespoke logic and one-off jobs are where Nornir can remain a good fit. See how automation and configuration management differ and the rConfig solution overview.

If NetBox or Infrahub is also your source of truth for rConfig, see rConfig with NetBox and rConfig with Infrahub. Those pages describe rConfig's integrations with NetBox and Infrahub, not an integration with Nornir. The integrations overview lists the rest.

What rConfig can cover, by edition

Not every edition includes every capability. This is how the current edition comparison on the rConfig site divides the capabilities discussed in this guide.

rConfig capabilities by edition, as listed in the edition comparison
EditionAdds
rConfig Core (free, open source)Scheduled backups, Compare configuration versions, Single sign-on
Starter and abovePolicy checks and compliance status, Role-based access control, RADIUS authentication, LDAP and Active Directory, User audit log, Restore a previous configuration, Push configuration changes
Standard and aboveCheck compliance continuously, Evidence you can hand to an auditor
Enterprise / MSPDistributed collectors, High availability, Manage every rConfig instance centrally

When it makes sense to stop building

This is not an argument against Nornir, and plenty of teams keep their Nornir code running alongside a platform. Whether to keep building the surrounding capabilities, adopt a platform for part of the work, or do both depends on your requirements, the engineering capacity you can give the work, and the infrastructure you already have. If your source of truth, scheduler, secret store and logging already meet the requirements in the production table, extending your scripts may be the best answer. These questions can help you decide:

  • Does an auditor need evidence that your scripts do not produce today?
  • Is maintaining the surrounding capabilities taking more of your time than the automation itself?
  • Do several teams need controlled access to the same collected configurations?
  • Is the work in the production table growing faster than the capacity you have to build and maintain it?

If the answers point that way, a platform that supplies some of those capabilities may be worth evaluating next to what you already run. rConfig V8 Core is free and open source, with no device limit, so you can run it next to your Nornir code and see which of the requirements it covers for your estate. If you want to talk through the paid editions, you can book a demo.

Nornir FAQ

What is Nornir?

An open source, pure Python automation framework that supplies an inventory, a multi-threaded runner and structured results, and leaves the task logic to your own Python code.

Is Nornir a Python library or a framework?

Its repository calls it a pluggable multi-threaded framework. You install it with pip and import it like a library, but it also supplies the structure around your code: an inventory, a runner and a plugin system.

How do I install Nornir?

In a virtual environment, run pip install nornir with the plugins you need, for example nornir-utils, nornir-netmiko or nornir-napalm. Nornir 3.6.0 needs Python 3.10 or newer.

Should I use Nornir or Ansible?

It depends mostly on how your team prefers to write and review automation: Python functions with Nornir, or YAML playbooks with Ansible. Some teams use both. The comparison table in this guide sets out the differences.

How does Nornir connect to network devices?

Through connection plugins. nornir_netmiko, nornir_napalm and nornir_scrapli add the Netmiko, NAPALM and Scrapli libraries, which handle each device session while Nornir runs the task across the inventory.

Can Nornir use NetBox as its inventory?

Yes, with the nornir_netbox inventory plugin, which builds the inventory from the NetBox API. Its latest PyPI release is dated 20 September 2021, so check it against your NetBox version in a lab first.

Is Nornir free, and who maintains it?

Yes. It is open source under the Apache-2.0 licence. David Barroso created it, and OpsMill is now its steward, with nornir.tech stating that the framework stays free and community-driven.

Can I use Nornir alongside rConfig?

Yes, they can run side by side, with Nornir for custom workflows and rConfig for configuration management. There is no native integration. The editions table in this guide shows which rConfig capabilities each edition includes.

Further reading and credit

Nornir

Plugins used in this guide

On rConfig

Thank you to David Barroso, who created Nornir; to OpsMill, for taking up its stewardship; and to the contributors who have built and maintained Nornir and its plugins for the whole community.