Nornir

3.5.0 verified Fri May 01 auth: no python

Nornir is a pluggable multi-threaded automation framework with inventory management for operating collections of network devices. It provides a pure Python approach to network automation without relying on a DSL. Current version is 3.5.0 (2024-09-16), released several times a year.

pip install nornir

Common errors

error ModuleNotFoundError: No module named 'nornir' ↓

cause Nornir is not installed.

fix

Run pip install nornir

error nornir.core.exceptions.NornirUnsupportedConfigSchema: Unsupported config schema ↓

cause The configuration dictionary passed to InitNornir does not match the expected schema (e.g., using a plugin not recognized).

fix

Ensure you are using the correct plugin names and options as per Nornir 3 documentation. For DictInventory, use inventory={'plugin': 'DictInventory', 'options': {...}}

error AttributeError: 'str' object has no attribute 'name' ↓

cause In Nornir 3, task function should accept a `Task` object, not a hostname string. The first argument is the task instance, and the host is accessed via `task.host`.

fix

Define your task function like: def my_task(task: Task) -> Result: host = task.host

error AttributeError: 'Nornir' object has no attribute 'run' ↓

cause Using Nornir 2.x style `nr.run()`. In Nornir 3, the method is `nr.run()` but the task function signature changed. If you see this error, you might be using an old version or mixing APIs.

fix

Ensure you are using Nornir 3.x and that your task function is defined correctly (accepts a single task argument).

Warnings

breaking Nornir 3.x introduced a completely new API compared to 2.x. The `InitNornir` function, inventory structure, and task execution model changed significantly. Existing Nornir 2.x code will not work without migration. ↓

fix Follow the official upgrade guide at https://nornir.readthedocs.io/en/latest/upgrading/2_to_3.html

gotcha Nornir's default runner is `ThreadedRunner`, which uses threading. This may cause issues with libraries that are not thread-safe (e.g., some SSH libraries). ↓

fix Use the `SerialRunner` to run tasks sequentially: `InitNornir(runner={'plugin': 'SerialRunner'})`

deprecated The `ParallelRunner` plugin was renamed to `ThreadedRunner` in v3.0.0a4. Using `ParallelRunner` will raise a deprecation warning. ↓

fix Use `'plugin': 'ThreadedRunner'` instead of `'plugin': 'ParallelRunner'`

Install

pip install nornir[paramiko]

Imports

InitNornir
wrong
```
from nornir.core import InitNornir
```
correct
```
from nornir import InitNornir
```
InitNornir is in the top-level nornir package since v3.0.

NRF

from nornir.plugins.functions import NRF

Filter

wrong

from nornir import Filter

correct

from nornir.core.filter import F

The F class is used for filtering hosts.

Quickstart

Basic example: initialize Nornir with an inline dict inventory, run a simple task, and print the result.

from nornir import InitNornir
from nornir.core.task import Task, Result

# Create a simple inventory definition inline
nr = InitNornir(
    inventory={
        "plugin": "DictInventory",
        "options": {
            "hosts": {
                "router1": {
                    "hostname": "192.0.2.1",
                    "username": "admin",
                    "password": "password"
                }
            }
        }
    }
)

# Define a task
def hello_task(task: Task) -> Result:
    return Result(host=task.host, result=f"Hello from {task.host.name}")

# Run the task
results = nr.run(task=hello_task)
print(results['router1'][0].result)

# Close connections if any
nr.close_connections()