NetBox: the source of truth for network infrastructure, and what it refuses to do

The problem NetBox solves: one intended-state database for the network

Spreadsheets, wiki pages and a few people's memory are the usual way network documentation starts. They break down for a specific reason: nothing validates them. A spreadsheet will happily record an IP address that is already assigned, a cable that terminates nowhere, or a VLAN ID that does not exist in that site. NetBox's job, as the README puts it, is to "define and validate the intended state of all network components and resources." Validation is the product, not the schema.

The audience is network engineers and the automation teams that sit next to them. The README describes NetBox as a successor to legacy IPAM and DCIM applications, and the data model reflects that lineage: racks, devices, cables, IP addresses, VLANs, circuits, power and VPNs are first-class objects that reference each other. A device lives in a rack, occupies units, has interfaces, and those interfaces connect through cables to other interfaces. IP addresses attach to interfaces. Because those links are enforced, an address cannot simply be typed into a free-text field and forgotten.

That is a different proposition from a general-purpose CMDB. The README argues directly against general-purpose tools, saying structured modeling of network primitives "just isn't possible" with them. Whether that is overstated is a fair question, but the underlying claim is concrete: the schema is opinionated about networks, and it is ready on installation rather than something you design first.

How NetBox works: a Django application with a REST API and no device access

NetBox is a Python application. The pyproject.toml declares requires-python = ">=3.12" and classifies the project under Framework :: Django; requirements.txt pins Django==6.1.1 along with djangorestframework==3.18.0, drf-spectacular==0.30.0 for the OpenAPI schema, strawberry-graphql and strawberry-graphql-django for a GraphQL endpoint, and Jinja2 for configuration rendering. PostgreSQL is the database (psycopg[c,pool]==3.3.5), Redis backs caching and the task queue (django-rq and rq), and gunicorn serves the application.

The architectural decision that matters most is stated in the README in one sentence: "NetBox does not interact with network nodes directly." NetBox holds intended state and hands it to other tools through APIs. The README's reference architecture diagram shows this as a hub: NetBox in the centre, with purpose-built automation, monitoring and assurance tools around it. The stated benefit is substitutability. You can replace the provisioning tool without touching the database of record.

Several features follow from that position. Custom scripts can be uploaded and run from the UI, prompting for input, which covers workflows that would otherwise be dozens of manual edits. Event rules trigger a script or an outbound webhook when something changes in NetBox, so a DHCP server or monitoring system can be notified when an IP range is allocated or a device is added. Jinja2 configuration templates can be rendered from NetBox's own data and retrieved through the REST API, then applied by a provisioning tool such as Ansible or Salt. NetBox produces the configuration text; something else delivers it.

Everything created, modified or deleted is logged, attributed to a user and grouped by request ID. For a database whose value depends on people trusting it, that audit trail is not a side feature.

Installing NetBox self-hosted and making a first API call

The README does not contain installation commands. It links to the project's documentation, and the repository ships an upgrade.sh script at the top level for upgrades. So the authoritative install procedure for your platform comes from the documentation, not from this page, and nothing here should be treated as a substitute for it. What the repository does state directly is the dependency set, and that set is the constraint that decides whether a host can run NetBox at all.

requirements.txt pins the runtime stack, and pyproject.toml sets the interpreter floor. Reading them together tells you what a machine must provide before NetBox will start. The Python floor is declared like this:

requires-python = ">=3.12"

The database driver is pinned in requirements.txt, which fixes PostgreSQL as the database rather than leaving the choice open. The pool and C extras are part of the pin, not optional decorations:

psycopg[c,pool]==3.3.5

Redis appears twice in the stack, once for caching and once for the task queue, and both packages are pinned:

redis==8.1.0
django-rq==4.2.0

Django itself is pinned to a specific release rather than a range, so the framework version a deployment runs is not a matter of interpretation:

Django==6.1.1

The upgrade path is scripted rather than manual. The top-level repository listing includes upgrade.sh, which is the file the project ships for moving between versions. Running it is the documented mechanism; a hand-rolled migration sequence is not.

./upgrade.sh

Once NetBox is running, the API is the point of the exercise. The REST API is served under /api/, and drf-spectacular provides the OpenAPI schema for the endpoints. The README states that rendered configurations can be retrieved via the REST API for application to network devices by a provisioning tool, so the read path your automation uses is the same one the UI uses.

Where NetBox is the wrong tool

NetBox will not configure a router. That is not a missing feature; the README makes the separation explicit, and anyone who buys NetBox expecting a controller has bought the wrong category of software. If your requirement is "change this BGP neighbour on forty devices and confirm it took," NetBox stores the intent and renders the template, but a provisioning tool has to do the work and an assurance tool has to confirm the result. Adopting NetBox without those pieces leaves you with a very well-documented network and no automation.

Adoption cost is real and front-loaded. The data model is comprehensive, which means someone has to populate it: sites, racks, device types, platforms, interfaces, cables, prefixes, VLANs. NetBox validates what you enter, so a half-migrated spreadsheet will produce errors rather than silently accepting contradictions. The README's claim that "everything is ready to go upon installation" is true of the schema and false of your data.

There is also a versioning constraint that shows up in the packaging. The optional extras for the NetBox Labs plugins are pinned to minor series: branching to >=1.1.0,<1.2.0 and custom-objects to >=0.5.0,<0.6.0. Those pins exist because plugins are tested against a NetBox series, and the comment in pyproject.toml notes that CI verifies the recommended-plugins aggregate equals the union of the two component extras to guard against drift. If your workflow depends on a plugin, a NetBox minor upgrade is a coordinated change, not a routine one. That is a maintenance cost you should price in before the first install, not after the third upgrade.

NetBox alternatives and the actual difference in approach

The most common alternative is a general-purpose CMDB or a configuration management database bolted onto an existing ITSM platform. The difference is the schema. A general CMDB gives you configuration items and relationships you define yourself; you then model a switch port as a CI with custom relationship types. NetBox ships the port as an object with a cable, a speed, a mode and a connected endpoint, and it refuses inconsistent combinations. The trade-off runs the other way too: a general CMDB can hold your application inventory, contracts and service catalogue in the same graph, and NetBox is deliberately not trying to. The README calls out "all-in-one" tools that "awkwardly bolt on half-baked features," which is a fair description of the failure mode and also an admission that NetBox will not cover everything.

A second alternative is infrastructure-as-code state files, such as a Terraform state or an Ansible inventory kept in Git. Those are genuinely the source of truth for what has been deployed, and they are version-controlled and reviewable. What they lack is a queryable model with referential integrity across the whole estate. You can ask Git what a playbook declares; you cannot easily ask it which interfaces in a site are unconnected. NetBox is the place to ask that question, which is why the README positions it as the authority that other tools read from rather than a replacement for them.

Neither alternative is worse in the abstract. If your network is small and your automation is a handful of playbooks, a Git repository is cheaper and has no database to run.

Licence, upgrade cost and what to verify before you commit

NetBox is licensed under Apache-2.0, declared in pyproject.toml with license-files = ["LICENSE.txt"], and the repository carries a NOTICE file alongside it. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve the licence and notice files in redistributed copies. The optional plugin extras for branching and custom-objects point at NetBox Labs plugins described in pyproject.toml as proprietary and opt-in, so a deployment that uses those features is not entirely Apache-2.0 code. Whether that matters depends on your distribution model, and it is worth reading the plugin licences yourself rather than inferring from the core licence.

Upgrades are the recurring cost. The repository ships upgrade.sh at the top level, which indicates the project expects upgrades to be a scripted procedure rather than an in-place package update, and the plugin version pins mean a NetBox minor release can require a coordinated plugin release. The release history shows a steady cadence: v4.7.1 on 2026-09-15, v4.7.0 on 2026-09-02, v4.6.10 on 2026-09-01, with the last push to the repository on 2026-09-18. This is a project that moves, and staying on a supported version means planning upgrade windows.

Before adopting, verify four things: that your Python is 3.12 or newer, that you can run PostgreSQL and Redis in your environment, that any plugin you depend on supports the NetBox series you intend to run, and that you have a separate tool ready to apply the configurations NetBox renders. The first three are checkable in an afternoon. The fourth is a project decision, and it is the one that determines whether NetBox improves your network or just documents it.

Editorial conclusion

Adopt NetBox if you need a structured, API-first record of intended network state and you already have separate tools for pushing configuration to devices. Do not adopt it expecting it to talk to routers or switches; the README states plainly that NetBox does not interact with network nodes directly. Before committing, verify that your Python version satisfies the >=3.12 requirement in pyproject.toml, that you can run PostgreSQL and Redis, and that your upgrade path can follow the shipped upgrade.sh script rather than a manual migration.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. netbox-community/netbox on GitHub
3. Project website
4. README
5. Releases