API & Integration
NetBox includes a slew of features which enable integration with other tools and resources powering your network.
Automation, workflows, and scripting
View all tagsNetBox includes a slew of features which enable integration with other tools and resources powering your network.
NetBox includes the ability to execute certain functions as background tasks. These include:
NetBox plugins can defer certain operations by enqueuing background jobs, which are executed asynchronously by background workers. This is helpful for decoupling long-running processes from the user-facing request-response cycle.
Branch operations, such as syncing and merging, are tracked as events. This record of events serves as a history for each branch.
v0.6.0
A change request is submitted to request approval of proposed changes in a branch before it can be merged. All rules of the assigned change policy must be met for the request to be approved. When submitting a change request for a branch, the owner selects the governing policy and designates a priority.
A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity).
Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the dcimsite table, which has columns named name, facility, physicaladdress, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the custom fields documentation for more information.
Users can add custom links to object views in NetBox to reference external resources. For example, you might create a custom link for devices pointing to a monitoring system. See the custom links documentation for more information.
Custom scripting was introduced to provide a way for users to execute custom logic from within the NetBox UI. Custom scripts enable the user to directly and conveniently manipulate NetBox data in a prescribed fashion. They can be used to accomplish myriad tasks, such as:
NetBox validates every object prior to it being written to the database to ensure data integrity. This validation includes things like checking for proper formatting and that references to related objects are valid. However, you may wish to supplement this validation with some rules of your own. For example, perhaps you require that every site's name conforms to a specific pattern. This can be done using custom validation rules.
While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs.
Each NetBox user can customize his or her personal dashboard by adding and removing widgets and by manipulating the size and position of each. Plugins can register their own dashboard widgets to complement those already available natively.
Data sources can be defined to reference data which exists on systems of record outside NetBox, such as a git repository or Amazon S3 bucket. Plugins can register their own backend classes to introduce support for additional resource types. This is done by subclassing NetBox's DataBackend class.
A data source represents some external repository of data which NetBox can consume, such as a git repository. Files within the data source are synchronized to NetBox by saving them in the database as data file objects.
Creating Models
The device discovery backend leverages NAPALM to connect to network devices and collect network information.
The Diode project is currently in Public Preview. Please see NetBox Labs Product and Feature Lifecycle for more details.
The Diode SDK is a Python library for sending data to the Diode server over gRPC/protbuf for ingestion in to NetBox.
reference architecture
Comprehensive guide to help determine if you need specialized cloud connectivity options for NetBox Cloud or if standard internet delivery meets your requirements.
NetBox includes the ability to automatically perform certain functions in response to internal events. These include:
An event rule is a mechanism for automatically taking an action (such as running a script or sending a webhook) in response to an event in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating an event for device objects and designating a webhook to be transmitted. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
Installation Issues
Form Classes
Overview of features and capabilities available in the NetBox Cloud Free Plan, including limitations and upgrade options.
This guide will help you set up and start using Diode to ingest data into NetBox.
Complete setup and configuration guide for NetBox Discovery across Cloud, Enterprise, and Community deployments with step-by-step instructions
This guide will help you get started with development on pynetbox. It covers setting up your development environment and running tests.
Setting up a Development Environment
Complete setup and configuration guide for NetBox Assurance - from installation to your first operational workflow with step-by-step instructions
You can view an on-demand Webinar Getting Started with Network Test Automation: NetBox + pyATS hosted by NetBox Labs.
This cheat sheet serves as a convenient reference for NetBox contributors who already somewhat familiar with using git. For a general introduction to the tooling and workflows involved, please see GitHub's guide Getting started with git.
NetBox includes a housekeeping management command that should be run nightly. This command handles:
NetBox
Before Starting
The instructions below detail the general process for installing and configuring a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin before attempting to install it.
Beginning with NetBox v4.0, NetBox will leverage Django's automatic translation to support languages other than English. This page details the areas of the project which require special attention to ensure functioning translation support. Briefly, these include:
Origin Story
The Job model is used to schedule and record the execution of background tasks.
This document summarizes the system-level changes made to a Linux host when installing a NetBox Enterprise Embedded Cluster, particularly in relation to directories, files, and runtime configurations affected under /.
NetBox Upgrade Maintenance Windows
This guide explains how to configure single sign-on (SSO) support for NetBox using Microsoft Entra ID as an authentication backend.
Complete guide to configuring single sign-on (SSO) for NetBox Cloud using Microsoft Entra ID (formerly Azure Active Directory) as an authentication backend.
Complete guide to migrating your existing NetBox deployment to NetBox Cloud, including data migration and configuration transfer.
Migrating from NetBox open source to NetBox Labs Enterprise is a simple and efficient process. Because NetBox Enterprise is built on the same open source platform, database imports can be completed quickly, enabling a smooth transition.
This document serves as a handbook for maintainers of plugins that were written prior to the release of NetBox v4.0. It serves to capture all the changes recommended to ensure a plugin is compatible with NetBox v4.0 and later releases.
ADMINS
Each module type may optionally be assigned a profile according to its classification. A profile can extend module types with user-configured attributes. For example, you might want to specify the input current and voltage of a power supply, or the clock speed and number of cores for a processor.
Menus
Automated operational drift detection for NetBox - continuously monitor network infrastructure and maintain accurate documentation with proactive remediation capabilities
NetBox is the world's leading source of truth for network infrastructure, featuring an extensive and complex data model. But sometimes it can be challenging to orchestrate changes, especially when working within a large team. This plugin introduces a new paradigm for NetBox to help overcome these challenges: branching.
This plugin adds change management support to NetBox. Leveraging the netbox-branching plugin, it implements policy and workflow controls to ensure proposed changes undergo formal review prior to being merged. It also retains a written record of all approved changes.
Advanced network discovery and observability solution for automated network documentation and drift detection across all NetBox deployments
1.10.1/1.10.2
Much like the NetBox software itself, NetBox Enterprise uses 2 main datastores: PostgreSQL, and Redis.
Advanced installation options for NetBox Enterprise Helm deployment
Basic installation guide using NetBox Labs Enterprise Portal
Overview of NetBox Enterprise Helm installation methods and architecture
System requirements and prerequisites for NetBox Enterprise Helm installation
Troubleshooting guide for NetBox Enterprise Helm installation issues
Host system requirements
This section of the documentation discusses installing and configuring the NetBox application itself.
NetBox Ansible Collection - Quick Start
Reports are deprecated beginning with NetBox v4.0, and their functionality has been merged with custom scripts. While backward compatibility has been maintained, users are advised to convert legacy reports into custom scripts soon, as support for legacy reports will be removed in a future release.
v2.0.10 (2017-07-14)
v2.10.10 (2021-04-15)
v2.11.12 (2021-08-23)
v2.2.10 (2018-02-21)
v2.3.7 (2018-07-26)
v2.6.12 (2020-01-13)
v2.7.12 (2020-04-08)
v2.8.9 (2020-08-04)
v2.9.11 (2020-12-11)
v3.0.12 (2021-12-06)
v3.1.11 (2022-04-05)
v3.2.9 (2022-08-16)
v3.4.10 (2023-04-27)
v3.5.9 (2023-08-28)
v3.6.9 (2023-12-28)
v3.7.8 (2024-05-06)
v4.0.11 (2024-09-03)
v4.1.11 (2025-01-06)
v4.2.9 (2025-04-30)
v4.3.3 (2025-06-26)
The network discovery backend leverages NMAP to scan networks and discover IP information.
A notification alerts a user that a specific action has taken place in NetBox, such as an object being modified or a background job completing. A notification may be generated via a user's subscription to a particular object, or by an event rule targeting a notification group of which the user is a member.
NetBox employs a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
This guide outlines the steps necessary for planning a successful migration to NetBox. Although it is written under the context of a completely new installation, the general approach outlined here works just as well for adding new data to existing NetBox deployments.
Just getting started with plugins? Check out our NetBox Plugin Tutorial on GitHub! This in-depth guide will walk you through the process of creating an entire plugin from scratch. It even includes a companion demo plugin repo to ensure you can jump in at any step along the way. This will get you up and running with plugins in no time!
This section covers the mechanisms which are available to populate data in NetBox.
Configure and manage IP prefix lists for NetBox Cloud security, including both synchronized and non-synchronized prefix list creation and management.
Looking to try NetBox Discovery as quickly and easily as possible? The Quickstart Guide on the NetBox Labs blog has you covered! In a few commands you will install and pre-configure everything you need to start experimenting:
Users can reserve specific units within a rack for future use. An arbitrary set of units within a rack can be associated with a single reservation, but reservations cannot span multiple racks. A description is required for each reservation, reservations may optionally be associated with a specific tenant.
This document outlines the steps required to prepare and publish a new release of pynetbox.
This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases:
ALLOWED_HOSTS
Filtering Objects
What is a REST API?
Once a branch has been merged, it is generally no longer needed, and can no longer be activated. However, occasionally you may find it necessary to undo the changes from a branch (due to an error or an otherwise undesired state). This can be done by reverting the branch. Only merged branches can be reverted.
Reviews are submitted to approve, reject, or comment on a change request. The users eligible to review a particular change request are determined by its assigned change policy.
When filtering lists of objects in NetBox, users can save applied filters for future use. This is handy for complex filter strategies involving multiple discrete filters. For example, you might want to find all planned devices within a region that have a specific platform. Once you've applied the desired filters to the object list, simply create a saved filter with name and optional description. This filter can then be applied directly for future queries via both the UI and REST API.
NetBox v3.4 introduced a new global search mechanism, which employs the extras.CachedValue model to store discrete field values from many models in a single table.
NetBox generally follows the Django style guide, which is itself based on PEP 8. ruff is used for linting (with certain exceptions).
A record indicating that a user is to be notified of any changes to a particular NetBox object. A notification maps exactly one user to exactly one object.
BASE_PATH
NetBox employs the django-tables2 library for rendering dynamic object tables. These tables display lists of objects, and can be sorted and filtered by various parameters.
New Tables in ServiceNow
Templates are used to render HTML content generated from a set of context data. NetBox provides a set of built-in templates suitable for use in plugin views. Plugin authors can extend these templates to minimize the work needed to create custom templates while ensuring that the content they produce matches NetBox's layout and style. These templates are all written in the Django Template Language (DTL).
NetBox coordinates all translation work using the Transifex platform. Signing up for a Transifex account is free.
A tunnel termination connects a device or virtual machine interface to a tunnel. The tunnel must be created before any terminations may be added.
Upgrading NetBox to a new version is pretty simple, however users are cautioned to always review the release notes and save a backup of their current deployment prior to beginning an upgrade.
Comprehensive guide to the NetBox Assurance web interface - navigation, deviation management, workflows, and daily operations for network drift detection
This plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.
Writing Basic Views
Code Structure
A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
The home of documentation for NetBox Cloud, Enterprise, Integrations, SDKs and Extensions.