Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
nornir-infrahub integrates Nornir with OpsMill Infrahub to manage network device data and automation artifacts. The installation process includes setting up the Python environment, configuring the InfrahubInventory plugin, and preparing the development toolchain for testing and documentation.
This guide covers production installation via pip and local development setup using uv. For details on how the system maps Infrahub nodes to Nornir objects, see the Architecture and Inventory Data Model references.
Sources: README.md:1-15, AGENTS.md:7-12, dev/knowledge/architecture.md:4-10
Prerequisites
Before installing the project, ensure your environment meets the following requirements:
- Python Version: Requires Python
>=3.10and<3.15. - Package Manager:
uvis recommended for dependency and virtual environment management. - External Services:
- Infrahub Instance: A reachable Infrahub API endpoint.
- Docker: Required only for running integration tests against live Infrahub containers.
- Node.js & npm: Required only for building or serving the Docusaurus documentation site.
Sources: pyproject.toml:9, dev/guides/local-development-setup.md:9-15, AGENTS.md:43-46
Standard Installation
Install the package directly from PyPI using pip. This installs the core library along with essential dependencies such as infrahub-sdk, nornir, and pydantic.
pip install nornir-infrahub
Sources: README.md:21-23, pyproject.toml:17-24
Core Dependencies
The project relies on specific versions of the following libraries:
| Dependency | Version Range | Purpose |
|---|---|---|
infrahub-sdk | >=1.20.1, <2 | Primary SDK for API interactions |
nornir | >=3.5.0, <4 | Core automation framework |
pydantic | >=2.0.0, <3 | Data validation and settings |
ruamel-yaml | >=0.18.17, <0.20 | YAML configuration processing |
| Sources: pyproject.toml:17-24, AGENTS.md:78-83 |
Local Development Setup
Contributors should use uv to manage the development environment. The uv sync command creates a virtual environment and installs all dev group dependencies, including pytest, ruff, and infrahub-testcontainers.
Environment Initialization
- Clone the repository.
- Run
uv syncto create the.venvand install dependencies. - (Optional) Activate the environment:
source .venv/bin/activate.
uv sync
Sources: dev/guides/local-development-setup.md:17-25, AGENTS.md:27-29
Development Workflow Architecture
The development environment utilizes invoke to orchestrate formatting, linting, and documentation tasks.
The diagram shows the relationship between the developer, the uv environment, and the invoke task runner used for quality gates.
Sources: tasks.py:16-110, dev/guides/local-development-setup.md:27-66
Plugin Configuration
The InfrahubInventory plugin must be registered or referenced in your Nornir configuration. It connects to the Infrahub API and maps node attributes to Nornir host data.
Inventory Options
When initializing Nornir, provide the following options to the InfrahubInventory plugin:
| Option | Type | Default | Description |
|---|---|---|---|
address | str | "http://localhost:8000" | The Infrahub API URL |
token | str | None | API token for authentication |
branch | str | "main" | Target Infrahub branch |
host_node | dict | Required | Defines the node kind (e.g., {"kind": "Device"}) |
schema_mappings | list | [] | Maps node attributes to Nornir host properties |
| Sources: nornir_infrahub/plugins/inventory/infrahub.py:136-160, dev/knowledge/architecture.md:16-24 |
Example Initialization
from nornir import InitNornir
from nornir.core.plugins.inventory import InventoryPluginRegister
from nornir_infrahub.plugins.inventory.infrahub import InfrahubInventory
# Register the plugin manually if not using entry points
InventoryPluginRegister.register("InfrahubInventory", InfrahubInventory)
nr = InitNornir(
inventory={
"plugin": "InfrahubInventory",
"options": {
"address": "http://localhost:8000",
"token": "YOUR_TOKEN",
"host_node": {"kind": "InfraDevice"},
"schema_mappings": [
{"name": "hostname", "mapping": "primary_address.address"},
],
},
}
)
Sources: nornir_infrahub/plugins/inventory/infrahub.py:145-177
Quality Gates and Verification
After installation, verify the setup by running the linting and testing suites.
Formatting and Linting
The project enforces strict code quality using several tools:
invoke format: Formats Python code withruffand Markdown withrumdl.invoke lint: Runsyamllint,ruff,pylint,ty(type checking), andrumdl.
Sources: tasks.py:19-72, AGENTS.md:33-41
Testing
Verify the installation by running tests:
- Unit Tests: Run
pytest(no Docker required). - Integration Tests: Run
pytest -m integration(requires a running Docker daemon).
Sources: dev/guides/local-development-setup.md:50-62, AGENTS.md:43-50
Documentation Server
If working on documentation, install Node.js dependencies and start the local server:
invoke docs-installinvoke docs-serve(accessible athttp://localhost:3000)
Sources: tasks.py:75-98, AGENTS.md:52-57
Nornir-Infrahub provides a flexible bridge between Infrahub's graph data and Nornir's automation capabilities. Proper installation ensures that both the inventory mapping logic and the task-based artifact management functions operate correctly within your automation environment.
Sources: dev/knowledge/architecture.md:4-10, README.md:11-15