Plugins

Nornir is a pluggable system and only very basic ones are included with nornir 3, for a list of third party plugins visit community plugins

Registering plugins

Starting with nornir3 some plugins need to be registered in order to be used. In particular:

inventory plugins
transform functions
connection plugins
runners

To do so you can use entry points or programmatically.

Using entrypoints in your setup.py:

setup(
    # ...
    entry_points={
      "PATH": "NAME = path.to:Plugin",
    }
)

In your pyproject.toml, if using a standards-based build tool like uv (recommended):

[project.entry-points."PATH"]
NAME = "path.to:Plugin"

Or, if using poetry:

[tool.poetry.plugins."PATH"]
"NAME" = "path.to:Plugin"

Where PATH is:

nornir.plugins.inventory - for inventory plugins
nornir.plugins.transform_function - for transform functions
nornir.plugins.runners - for runners
nornir.plugins.connections - for connection plugins

Where NAME is the way you want to refer to it later on and path.to:Plugin the import path. For instance:

[project.entry-points."nornir.plugins.inventory"]
inventory-name = "path.to:InventoryPlugin"

To do it programmatically import the correct plugin register and use the register method. For instance:

from nornir.core.plugins.inventory import InventoryPluginRegister

from path.to import InventoryPlugin

InventoryPluginRegister.register("inventory-name", InventoryPlugin)

Connections

A connection plugin is a nornir plugin that allows nornir to manage connections with devices

Inventory

An inventory plugin is a nornir plugin that allows nornir to create an Inventory object from an external source

Included

class nornir.plugins.inventory.__init__.SimpleInventory(host_file: str = 'hosts.yaml', group_file: str = 'groups.yaml', defaults_file: str = 'defaults.yaml', encoding: str = 'utf-8')

load() → Inventory

Build the inventory from the YAML files given to the constructor.

Only the hosts file is required. A missing groups or defaults file is skipped, and a file that is empty or holds nothing but comments is treated as empty and logged as a warning. The group names the hosts refer to are resolved into the group objects themselves, so a name that is not in the groups file is an error.

Returns:: The inventory the files describe.
Return type:: nornir.core.inventory.Inventory

Transform functions

A transform function is a plugin that manipulates the inventory independently from the inventory plugin used. Useful to extend data using the environment, a secret store or similar.

During inventory initialization, the transform function will be called in a for loop for each host. The transform function takes a host object as the first parameter and additional keyword arguments as specified in the config.inventory.transform_function_options dictionary.

Runners

A runner is a plugin that dictates how to execute the tasks over the hosts

Included

class nornir.plugins.runners.__init__.SerialRunner

Runner that executes the task over each host sequentially without parallelization.

run(task: Task, hosts: list[nornir.core.inventory.Host]) → AggregatedResult

Run the task against each host, one after the other.

A host whose task raises does not stop the ones after it: the exception is recorded in that host’s result instead of propagating.

Parameters:

task – Task to run. Each host gets its own copy of it
hosts – Hosts to run the task against

Returns:

The results, keyed by host name.

Return type:

nornir.core.task.AggregatedResult

class nornir.plugins.runners.__init__.ThreadedRunner(num_workers: int = 20)

Runner that executes the task over each host using threads.

Parameters:: num_workers – number of threads to use

run(task: Task, hosts: list[nornir.core.inventory.Host]) → AggregatedResult

Run the task against the hosts, num_workers of them at a time.

The call returns once every host is done. A host whose task raises does not affect the others: the exception is recorded in that host’s result instead of propagating.

Parameters:

task – Task to run. Each host gets its own copy of it
hosts – Hosts to run the task against

Returns:

The results, keyed by host name.

Return type:

nornir.core.task.AggregatedResult

For more details about ThreadedRunner read the Execution Model.

Processors

A processor is a plugin that taps into certain events and allows the user to execute arbitrary code on those events.