Nautobot v3.0

This document describes all new features and changes in Nautobot 3.0.

Upgrade Actions

Administrators

Job approval permissions have been updated in the UI and API. Approvers must now be granted the extras.change_approvalworkflowstage and extras.view_approvalworkflowstage permissions, replacing the previous requirement for extras.approve_job. This change aligns with updates to the approval workflow implementation and permissions model.
The approval_required field from extras.Job model has been removed. This is a breaking change for any custom Jobs or applications that reference this field. This functionality has been replaced by a new approval workflow system. For more information on how the new approach works, see approval workflow documentation
- If you're upgrading from Nautobot 2.x, a management command, nautobot-server check_job_approval_status is available in 2.x to help identify jobs and scheduled jobs that still have approval_required=True. Running this command prior to upgrading can help you detect and address these cases by either clearing scheduled jobs or defining approval workflows for Jobs.
- To maintain a similar approval process, see the steps in predefined approval workflow.
A small number of breaking filter field changes may impact Dynamic Group filter definitions; you are recommended to run nautobot-server validate_models extras.dynamicgroup (or the newly added Validate Model Data system Job) after the upgrade to identify any impacted Dynamic Groups.

Job Authors & App Developers

Apps that provide any user interface will likely require updates to account for the Bootstrap upgrade from v3.4 to v5.3 described below.
The Data Compliance feature set from the Data Validation Engine App has been moved directly into core. Import paths that reference nautobot_data_validation_engine.custom_validators.DataComplianceRule or nautobot_data_validation_engine.custom_validators.ComplianceError should be updated to nautobot.apps.models.DataComplianceRule and nautobot.apps.models.ComplianceError, respectively.
Code that calls the GraphQL execute_query() and execute_saved_query() functions may need to be updated to account for changes to the response object returned by these APIs. Specifically, the response.to_dict() method is no longer supported, but instead the returned data and any errors encountered may now be accessed directly as response.data and response.errors respectively.

REST API Users

Filtering data that supports a type filter in the REST API now also supports a corresponding type filter in GraphQL. (In Nautobot v2.x and earlier, the filter had to be referenced in GraphQL as _type instead.) Filtering by _type is still supported where applicable but should be considered deprecated; please update your GraphQL queries accordingly.
As a part of adding support for associating a Device to multiple Clusters, the Device REST API no longer supports a cluster field; the field has been renamed to clusters and is now a list of related Clusters rather than a single record. See below for more details.
The REST API now defaults to excluding many-to-many fields (except for tags, content_types, and object_types) by default. Any code that relies on including many-to-many fields in the REST API response must explicitly request them by specifying the exclude_m2m=False query parameter. Pynautobot and Nautobot Ansible users should ensure they are on the latest versions to maintain backwards compatibility. See Many-to-Many Fields in REST API below for more details.

Release Overview

Breaking Changes

Many-to-Many Fields in REST API (#7456)

In order to improve performance at scale, the REST API now defaults to excluding many-to-many fields (except for tags, content_types, and object_types) by default. Any code that relies on including many-to-many fields in the REST API response must explicitly request them by specifying the exclude_m2m=False query parameter. See Filtering Included Fields for more details.

Pynautobot users should ensure they add exclude_m2m=False to an individual request (nb.dcim.devices.all(exclude_m2m=False)) or (in pynautobot v3.0.0+) set the default for all requests (import pynautobot; nb = pynautobot.api(url, token, exclude_m2m=False)) to maintain prior behavior.

Nautobot Ansible users (using v6.0.0+ and pynautobot v3.0.0+) should see no change required when using module or inventory plugins. When using a lookup plugin, however, they will need to use the api_filters parameter to include M2M fields. For example: api_filters='exclude_m2m=False'.

Removed Python Code

Many previously deprecated classes have been fully removed now (see full table below). The most notable removal is the original PluginConfig class, which was replaced by NautobotAppConfig in v1.5.2. If your app still imports and inherits from PluginConfig, you should migrate to using NautobotAppConfig before upgrading to Nautobot 3.0.

To assist with identifying any remaining instances of deprecated code in your codebase, new rules have been added to pylint-nautobot in version v0.4.3+ that will flag any code that still imports and inherits from any of the deprecated classes.

ℹ️ Full table of code removals

Removed HTML Templates

Many legacy HTML templates have been removed. The majority of the removed templates are model specific such as circuits/circuit.html or dcim/device/base.html and have been superseded by generic templates such as generic/object_retrieve.html.

In order to ease the transition from these deprecated templates for app developers, we have included a migration script in Nautobot v2.4.21+ that will recursively parse through a directory's html files and replace any extends directives ({% extends ... %}) that reference a deprecated template with the replacement template. This script does not require Nautobot to be running and it can be run with the command nautobot-migrate-deprecated-templates <path> [--dry-run]. For more details, including a full table of deprecated templates and their replacements, see Deprecated Templates.

Removed Branding Options

Removed support for branding configuration options of header_bullet, nav_bullet, javascript, and css. Bullets are no longer used at all in the 3.0 design.

Added

UI Updates

Nautobot 3.0 introduces a refreshed user interface, building on the migration from Bootstrap 3 to Bootstrap 5 with several major enhancements:

Search

The search experience has been completely reimagined. A single, always-available search bar is now present throughout the application, accessible via Ctrl+K or Command+K. Advanced search syntax, such as in:<model name>, allows you to target specific models directly. The search results page now provides clearer visibility into active search parameters and makes it easy to distinguish between basic and advanced queries.

Saved Views

Saved Views have been improved to display their type more prominently, making it easier to identify when a Saved View is active and to understand the filters or configurations being applied. This streamlines workflows and reduces confusion when working with complex data sets.

Navigation Bar

The Navigation Bar has been redesigned for greater efficiency and usability. It now features support for marking items as favorites, incorporates intuitive icons, and uses a modern flyout design to maximize space and accessibility. Navigation is more consolidated, helping users quickly find and access key areas of Nautobot.

Load Balancer Models

Nautobot 3.0 introduces a Load Balancer data model, enabling you to model Virtual Servers, Pools, Pool Members, Health Checks, and Certificates. This feature provides compatibility for configuration generation (via Golden Configuration) with popular load balancing vendors such as F5, Citrix NetScaler, A10 Networks, VMware Avi Load Balancer, and Fortinet.

Key use cases include:

Modeling load balancer resources for service, application, and inventory tracking.
Generating device configurations using Nautobot Golden Configuration templates for supported vendors.
Mapping Virtual Servers to backend servers and services.
Managing certificate configuration and associated metadata.

VPN Models

Nautobot 3.0 adds a VPN data model to support modeling Virtual Private Networks (VPNs), including reusable profiles, policies, and tunnel endpoints. These models enable you to define IKE (Phase 1) and IPSec (Phase 2) policy parameters, manage tunnel endpoints, and associate VPNs with roles and secrets. Additionally, VPNs may optionally be associated with tenants so that administrators can indicate ownership of related model instances.

Key Use Cases include:

Site-to-site IPSec VPN tunnel (transport mode)
Site-to-site IPSec VPN tunnel (tunnel mode)
Single hub-and-spoke VPN
Multiple hub-and-spoke VPNs

Device Uniqueness Flexibility

Device Uniqueness is now less restrictive. Current behavior of Location + Tenant + Name is maintained in migration, but now in addition you can configure to Device name must be globally unique and No enforced uniqueness as well as you can set Device name required (cannot be blank or null).

Approval Workflows

Approval Workflows allows for a multi-stage review and approval of processes before making changes, running or creating specific objects in the system. They are defined in advance and attached to specific models based on certain constraints. Use cases include:

Preventing accidental deletion of critical data by requiring manager approval before deletion jobs run.
Requiring security team sign-off before enabling network changes in production.
Ensuring multiple stakeholders approve large-scale bulk edits.
Mandating peer review for scheduled jobs that affect multiple systems.

Data Validation Engine

The Nautobot Data Validation Engine functionality previously provided as a separate Nautobot App has been migrated into Nautobot as a core feature.

The data validation engine offers a set of user definable rules which are used to enforce business constraints on the data in Nautobot. These rules are tied to models and each rule is meant to enforce one aspect of a business use case.

Supported rule types include:

Regular expression
Min/max value
Required fields
Unique values

Additionally Data Compliance allows you to create validations on your data without actually enforcing them and easily convert them to enforcements once all of your data is compliant.

ECharts

ECharts is now included in the base image, with abstractions provided to easily add custom charts using ECharts.

GraphQL

You will notice a fresh new look for the GraphiQL interface, which has been upgraded to version 2.4.7. This update brings a modernized UI, improved usability, and better alignment with Nautobot's theming. Most user workflows remain unchanged, but you may find enhanced features such as improved query editing, autocompletion, and response formatting.

Changed

Bootstrap upgrade from v3.4 to v5.3

Nautobot now uses Bootstrap v5.3 as its underlying theming and layout engine. The base Nautobot UI has been refreshed accordingly. Apps will generally require corresponding updates for their UI to render properly. The impact of this upgrade will be much reduced if the App has already adopted the UI Component Framework introduced previously in Nautobot v2.4. A migration script is included in Nautobot 3.x to automate many of the HTML and CSS updates for App developers.

Device to Multiple Clusters (#7203)

The Device model has replaced its single cluster foreign-key field with a many-to-many clusters field, allowing multiple Clusters to be associatd with a single Device.

To provide a modicum of backwards-compatibility, the Device model and queryset still support a singular cluster property which can be retrieved and (in some cases) set for the case of a single associated Cluster, but App authors, Job Authors, and GraphQL users are encouraged to migrate to using clusters as soon as possible. The cluster property will raise a MultipleObjectsReturned exception if the Device in question has more than one associated Cluster.

Note that due to technical limitations, the Device REST API does not support a cluster field in Nautobot v3, so users of the REST API must migrate to reading the clusters field where applicable. Assignment of Devices to Clusters via the REST API is now managed via a dedicated endpoint /api/dcim/device-cluster-assignments/ similar to other many-to-many fields in Nautobot.

Filter Standardization Improvements (#1889)

To make Nautobot's UI, REST API, and GraphQL filters more self-consistent and standardized, the default filter type for foreign-key and one-to-one model fields has been changed from a single-value filter (ModelChoiceFilter) to a multi-value filter (ModelMultipleChoiceFilter). This change affects a small number of filters in Nautobot core, as most such fields were already explicitly covered by a ModelMultipleChoiceFilter or one of its derivatives, but the following implicit filters are known to have been affected by this change (in addition to any App model filters on one-to-one and foreign-key fields that also were not explicitly defined otherwise):

Front Port Templates rear_port_template filter
Power Outlets power_port filter
Module Bays parent_module filter
Job Log Entries job_result filter
Job Results user filter
IP Address to Interface ip_address filter

For users of the UI and REST API, this is purely a feature enhancement to the above filters, as specifying single values in the URL query parameters remains supported, but multiple values are also supported now (for example /api/extras/job-log-entries/?job_result=<uuid1>&job_result=<uuid2>.)

For users of GraphQL, this is also a feature enhancement, as queries using the above filters can now specify either a single value (job_log_entries (job_result: "<uuid>") { message }) as before, or can now be updated to specify a list of values instead (job_log_entries (job_result: ["<uuid1>", "<uuid2>"]) { message }) if desired.

⚠️ Impact to Dynamic Groups
For Dynamic Groups using the above filters, the group filter will need to be updated to replace the single string value with a list of strings, for example changing:

{"rear_port_template": "74aac78c-fabb-468c-a036-26c46c56f27a"}

{"rear_port_template": ["74aac78c-fabb-468c-a036-26c46c56f27a"]}

You can identify impacted Dynamic Groups by running the nautobot-server validate_models extras.dynamicgroup management command, or the new Validate Model Data system Job; in the above case, the invalid group filter would be reported as below:

# nautobot-server validate_models extras.dynamicgroup
Validating 1 models.
extras.DynamicGroup
~~~~~ Model: `extras.DynamicGroup` Instance: `Front Port Template Legacy` Error: `{'rear_port_template': ['Enter a list of values.']}`. ~~~~~

Removed

Button on Navbar

Buttons were removed from the NavBar as our research indicated they were infrequently used and caused clutter.

Job Approval Process

The Job Approval process was removed and replaced by Workflow Approvals.

Dependencies

GraphQL and GraphiQL Updates

The underlying GraphQL libraries (graphene, graphene-django, graphene-django-optimizer) used by Nautobot have been updated to new major versions, including a new major version of the GraphiQL UI. For the most part this upgrade will be seamless to end users, but the response object returned by Nautobot's execute_query() and execute_saved_query() Python APIs has changed type -- see Upgrade Actions above for specifics.

Added Python 3.13 Support and Removed Python 3.9 Support

As Python 3.9 has reached end-of-life, Nautobot 3.0 requires a minimum of Python 3.10. Python 3.13 support was added.

Added Echarts

Added the JavaScript Library ECharts version 6.0.0.

Contributors

Full Changelog: v2.4.22...v3.0.0

nautobot/nautobot v3.0.0 v3.0.0 - 2025-11-17 on GitHub