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)
- Sources
- GitHub · Documentation · PyPI
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.
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.
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.
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.
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.
---
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
---
ios:
platform: ios
junos:
platform: junos
dc1:
data:
site: dc1
dc2:
data:
site: dc2
# inventory/defaults.yaml
---
port: 22Filtering 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 ~.
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.
python3 -m venv .venv
source .venv/bin/activate
pip install nornir nornir-utils nornir-netmiko nornir-napalmTake 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 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"---
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.logThe 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.
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)$ 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.
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 passwordNornir 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.
| PyPI package | Provides | Latest release on PyPI | Author on PyPI |
|---|---|---|---|
| nornir-netmiko | Netmiko connection plugin and tasks | 1.0.1, 7 December 2023 | Kirk Byers |
| nornir_napalm | NAPALM connection plugin and tasks | 0.6.0, 3 August 2026 | David Barroso |
| nornir-scrapli | Scrapli connection plugins and tasks | 2025.1.30, 31 January 2025 | Carl Montanari |
| nornir-utils | print_result, YAMLInventory, load_credentials, write_file and other helpers with no external dependencies | 0.3.0, 3 August 2026 | David Barroso |
| nornir_jinja2 | Tasks that render Jinja2 templates | 1.0.0, 3 August 2026 | David 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.
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.
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.
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.
ntp server 198.51.100.123from 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 diffScrapli: 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.
pip install nornir-scrapli "scrapli==2025.1.30"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.
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.
pip install nornir_jinja2Rendering 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.
ntp server {{ ntp_server }}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.
pip install nornir-netboximport 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.
pip install nornir-infrahubimport 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.
| Aspect | Nornir | Ansible |
|---|---|---|
| How you write automation | Python. 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 |
| Inventory | Hosts, 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 |
| Concurrency | A 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 devices | Through 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 |
| Ecosystem | A community plugin list in the Nornir documentation, plus the whole Python ecosystem for anything else. Source | Collections 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.
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.
---
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: junosThread 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.
---
logging:
level: DEBUG
log_file: nornir.log
to_console: falseInventory 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.
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.
| Requirement | Why it matters | How teams can provide it |
|---|---|---|
| Inventory and a source of truth | Nornir 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 limiting | Many 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 visibility | Regular 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 diff | Collecting 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 checks | Checking 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 people | Once 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 rotation | Environment 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 trail | Auditors 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 availability | If 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 breakage | Plugins 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.
| Edition | Adds |
|---|---|
| rConfig Core (free, open source) | Scheduled backups, Compare configuration versions, Single sign-on |
| Starter and above | Policy 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 above | Check compliance continuously, Evidence you can hand to an auditor |
| Enterprise / MSP | Distributed 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
- Nornir on GitHub, the official project
- Documentation and the tutorial
- Nornir on PyPI
- The community plugin list
- nornir.tech and OpsMill's announcement
Plugins used in this guide
- nornir_netmiko and nornir_napalm
- nornir_scrapli, nornir-utils and nornir_jinja2
- nornir-netbox on PyPI and nornir-infrahub
On rConfig
- The Netmiko guide, the Paramiko guide and the Batfish guide
- The rConfig solution overview
- Integrations
- Network automation vs configuration management
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.