How to Use NetBox: The Beginner's Guide (First Install, the SECRET_KEY Rule, First Prefix, and the Source-of-Truth Lesson)

CodexFuse Team · 2026-11-01T00:50:00.000Z · 16 min read

Every growing network reaches the moment when the IP spreadsheet lies to someone. Two engineers claim the same /24, a decommissioned server's address gets reissued to a new VM, and the VLAN map in the shared drive is three redesigns out of date. Learning how to use NetBox is how teams replace that fragile spreadsheet with a single database everyone trusts: NetBox is the open-source IP address management (IPAM) and data center infrastructure management (DCIM) tool from the NetBox community that records the intended state of your network — sites, prefixes, IP addresses, devices, racks, and cables — and serves it back through a clean web UI and a full REST and GraphQL API.

This beginner tutorial walks the whole first journey in one place: installing NetBox with Docker, the two configuration rules that break almost every first install, creating your first site and prefix, the source-of-truth lesson that changes how you think about network data, and a first automation script with the official pynetbox SDK. Before you carve up address space, sketch the plan with a subnet calculator so your prefix boundaries are decided on paper before they are typed into the database.

What is NetBox?

NetBox is an open-source network infrastructure modeling application: it documents and manages IP addresses (IPAM) and data center infrastructure (DCIM) — sites, racks, devices, cables, VLANs, VRFs, prefixes, and IP addresses — in one cohesive data model, exposed through a web UI and programmable APIs. Its tagline in the official repository is "the cornerstone of every automated network," and since its release in 2016 it has become the go-to solution for modeling and documenting network infrastructure for thousands of organizations worldwide, per the project's own README.

The DCIM half is what separates NetBox from a pure IPAM tool. An IP address manager tracks address space; NetBox also tracks the physical reality around it: which rack a switch lives in, which port its cable lands on, and which circuit connects the site. Everything connects back to the same objects, so the IP address, the device holding it, and the cable connecting that device are three views of one documented truth.

How do you install NetBox?

Install NetBox with Docker using the community netbox-docker project: it is the fastest reliable path for a beginner, and the supported stacks are explicit — PostgreSQL 15 or newer for the database and Redis 6.0 or newer for caching and task queuing, on a host running a current Python (the official install docs list Python 3.12, 3.13, and 3.14 and say the instructions were tested on Ubuntu 24.04). If you are new to containers, our Docker beginner guide covers the runtime basics first; for the server itself, see what is VPS hosting to pick a home for the stack.

The quickstart from the official netbox-docker README runs four commands:

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp docker-compose.override.yml.example docker-compose.override.yml
docker compose pull
docker compose up

Cloning with -b release matters: it pins you to the tested release branch instead of the moving main branch. After a few minutes the whole application — NetBox plus PostgreSQL, Redis, and a worker — is up, and the web UI is waiting at http://0.0.0.0:8000/. Then create the first admin account exactly as the README shows:

docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

Log in with those credentials and you will see the NetBox dashboard with sections for DCIM, IPAM, and the other modules. If you plan to rebuild from an empty database often during learning, the README notes you can set the SUPERUSER_* variables in your override file instead of running the createsuperuser step every time. The alternative to Docker is the native install path — release archive or Git checkout plus Gunicorn and an HTTP server, per the official install docs — but note that installing NetBox from the Python package is marked experimental in v4.7 and not recommended for production.

Which two configuration rules break almost every first install?

Two settings in configuration.py cause the majority of first-install failures: SECRET_KEY and ALLOWED_HOSTS. Treat them as a pre-flight checklist before you ever open the login page.

First, the SECRET_KEY. NetBox's own example configuration states that the key should be at least 50 characters long with a mix of letters, numbers, and symbols — and that NetBox will not run without one defined. This is the number-one beginner security miss: people leave the generated sample value in place. Generate a real one; a common way is Python's secrets module, e.g. python3 -c "import secrets; print(secrets.token_urlsafe(64))", then paste the output as your SECRET_KEY. Never commit the file containing it to a public repository.

Second, ALLOWED_HOSTS. The example ships it as an empty list, and the first fully-qualified domain name in the list is treated as the preferred name. If you deploy NetBox behind a domain name and leave this empty, your first login attempt fails with a host rejection. Add your FQDN — for example ALLOWED_HOSTS = ['netbox.example.com'] — before you test remote access. This single setting is the number-one install failure in community threads: everything works on localhost, and everything breaks the moment you use the real hostname.

How do you use NetBox, step by step?

Use NetBox by building the model top-down — organization first, address space second, devices last — in ten steps that take you from an empty install to an automated source of truth:

1. Install and start the stack. Follow the Docker quickstart above; confirm the UI loads at your host's port 8000.
2. Create the admin user with the createsuperuser command and log in.
3. Set SECRET_KEY and ALLOWED_HOSTS in configuration.py (or the Docker equivalent) and restart.
4. Add a region and a site. Under Organization, create a region (e.g. "North America"), then a site inside it (e.g. "HQ"). Sites anchor everything else — prefixes, VLANs, racks, and devices all hang off a site.
5. Create your first aggregate/prefix. Under IPAM, add the top-level block your organization owns, e.g. 10.10.0.0/16, marked with a role and description.
6. Carve the first child prefix. Add 10.10.10.0/24 as a child of the /16 with status "Active" — this is your first real subnet record.
7. Add individual IP addresses. Under IPAM, create addresses like 10.10.10.10/24 with status "Active" or "Reserved".
8. Document one device (optional but instructive). Add a manufacturer, a device type, a rack at your site, then the device itself — and assign the IP to its interface.
9. Enable the API and mint a token. In your user profile, generate an API token; this is the credential automation uses.
10. Run your first pynetbox script to read and create objects programmatically (full example below).

That order is deliberate. Beginners who start by adding random IP addresses end up with orphans; beginners who build region → site → prefix → IP produce a model that stays coherent as it grows. The community guide on adding sites makes the same point: manual entry takes time, so understanding the hierarchy before automating it is the whole game.

How do you plan your first address space?

Plan your address space on paper before typing a single prefix into NetBox: decide the aggregate each site owns, the VLAN-to-subnet mapping, and which ranges stay reserved. A workable starter plan for a two-site organization looks like this:

Two habits make this plan survive contact with reality. First, reserve the management and loopback ranges on day one — "Reserved" is a real prefix status in NetBox, and carving space you cannot later reclaim is the classic addressing regret. Second, keep aggregates generous: a /16 per site feels wasteful until the third VLAN expansion. When you are unsure of boundary math, run the numbers through an IP range calculator before committing them to the database.

How do you add your first prefixes and IP addresses?

Add prefixes under IPAM → Prefixes → Add, and addresses under IPAM → IP Addresses → Add: each record takes the network value, a status, a role, a tenant or site, and a description, and NetBox validates the hierarchy for you. Prefix statuses worth learning on day one are Active (in use), Reserved (held for future use), and Deprecated (being retired) — using them honestly is what makes utilization views meaningful later.

Watch how the UI nests things. When you view the 10.10.0.0/16 aggregate, its child prefixes appear inside it, and each child's utilization bar reflects the addresses assigned within. That nesting is the whole point of modeling in NetBox rather than a flat spreadsheet: the database knows that 10.10.10.0/24 belongs to the /16, and it will stop you from creating an overlapping sibling. Overlapping-prefix protection is one of the first "the spreadsheet never did this" moments new users report.

For addresses, assign them to interfaces when you can. An IP record floating unassigned is just an inventory line; an IP assigned to a device interface becomes part of the documented topology. Add DNS names to address records too — NetBox stores them, and they become the seed data for the DNS-sync automation you will build later.

What does "source of truth" actually mean in NetBox?

"Source of truth" means NetBox records the intended state of your network — what should exist — not the live state of what is actually reachable right now. The project's own README states this plainly: NetBox defines and validates the intended state of all network components and resources, and it does not interact with network nodes directly. Monitoring tools, config-management systems, and assurance platforms then read that intended state programmatically and compare it against reality.

This is the lesson that decides whether NetBox clicks for you. A common beginner misconception — flagged in community IPAM guides as well — is treating NetBox like a network monitoring system or packet sniffer. It is neither. If a switch dies, NetBox will not page you; it will simply continue to document what the network is supposed to look like, which is exactly what your automation needs to rebuild it correctly.

The scanner reality follows from this: NetBox core has no built-in network discovery, and the well-known netbox-scanner plugin approach is years old. If you want live reachability data next to your documented intent, run a scan with a separate tool — a port scanner shows you what is actually listening right now — and compare the result against NetBox. That comparison, documented intent versus observed reality, is the professional workflow NetBox was designed to sit in the middle of.

How do you automate NetBox with pynetbox?

Automate NetBox with pynetbox, the official Python SDK: it mirrors NetBox's app structure, so nb.ipam.prefixes is the prefixes endpoint and nb.dcim.devices is the devices endpoint, with .get(), .filter(), .all(), .create(), .save(), and .delete() covering the full object lifecycle. The official quick-start docs are current for the v4 API surface, including newer details like strict_filters (invalid filter parameters are silently ignored by default, so enable it to catch typos) and the one-shot nature of RecordSet (materialize with list() if you need to iterate twice).

A first script that reads your database and creates a prefix looks like this:

import os
import pynetbox

nb = pynetbox.api("http://localhost:8000",
                  token=os.environ["NETBOX_API_TOKEN"])

# 1. Find the parent prefix created in the UI
parent = nb.ipam.prefixes.get(prefix="10.10.0.0/16")

# 2. See what space is still free inside it
for free in parent.available_prefixes.list()[:5]:
    print("Available:", free)

# 3. Create a new /24 for the server VLAN
new_prefix = nb.ipam.prefixes.create(
    prefix="10.10.10.0/24",
    status="active",
    description="Server VLAN - Building A",
)
print("Created:", new_prefix.prefix)

Three practical notes. First, the API token is required for write operations and for non-public endpoints — keep it in an environment variable, never in the script. Second, the SDK exposes plugin endpoints under the plugins namespace, so community plugins stay automatable the same way. Third, older community tutorials (some date back to NetBox v2) still show valid patterns, but verify field names against the built-in API docs at /api/docs/ on your own instance — device_role becoming role in v3.6 is the classic example of a renamed field breaking an old script.

NetBox vs phpIPAM: which should a beginner pick?

Pick NetBox when you want the full infrastructure model (IPAM plus DCIM), and phpIPAM when you want a lighter, IPAM-focused tool: both are free and open source, both ship a REST API and Docker deployment, and the honest differences are scope and weight. The table below uses only each project's own published facts.

The interesting row is discovery. If "scan my subnets and tell me what is alive" is your first requirement, phpIPAM ships that natively while NetBox deliberately does not — it is a documentation system that other tools feed. Beginners choosing NetBox are choosing the model-first philosophy: document intent carefully, then let automation and monitoring consume it.

What mistakes do beginners make most?

Beginners make the same five mistakes in NetBox, and all five are cheaper to avoid than to fix:

Should you self-host, or start on NetBox Cloud?

Start on NetBox Cloud's free plan if you want to learn the data model without operating the stack: the official install docs advertise a free Cloud tier that skips installation entirely and hands you a preconfigured instance in minutes. It is the fastest way to run the ten-step arc above and decide whether the NetBox way of thinking fits your team.

Self-host when the data must live on your infrastructure — regulated environments, air-gapped networks, or plugin and integration needs the Cloud tier does not cover. The Docker path above is the self-hosting on-ramp, and everything you learn on Cloud transfers directly: the data model, the UI, and the API are the same. Either way, the current release line at the time of writing is v4.7.x (v4.7.4 was released 2026-10-27), so any tutorial referencing v2 or v3 field names deserves a cross-check against your instance's /api/docs/.

Sources

NetBox GitHub repository (netbox-community/netbox) — v4.7.4 released 2026-10-27, ~21,825 stars, Apache-2.0, repository created 2016-02-29 (GitHub REST API, fetched 2026-11-01); NetBox README v4.7.4 — "the cornerstone of every automated network," source-of-truth/intended-state definition, "does not interact with network nodes directly" (raw README, fetched 2026-11-01); NetBox installation docs (docs.netbox.dev, crawled 2026-11-01) — Ubuntu 24.04, Python 3.12–3.14, PostgreSQL 15+, Redis 6.0+, experimental Python package in v4.7, NetBox Cloud free plan; netbox-docker README (raw, fetched 2026-11-01) — quickstart commands, port 8000, createsuperuser path, SUPERUSER_* variables, -b release branch; configuration_example.py v4.7.4 (raw, fetched 2026-11-01) — SECRET_KEY 50+ character rule, "NetBox will not run without this defined," ALLOWED_HOSTS semantics; pynetbox quick-start docs (netboxlabs.com, crawled 2026-11-01) — connection pattern, app/endpoint mapping, strict_filters, RecordSet behavior, token requirement for writes; phpIPAM homepage (phpipam.net, crawled 2026-11-01) — free open-source IPAM, IPv4/IPv6, VLAN management, REST API, Docker, automatic subnet scanning, version 1.8; phpIPAM GitHub repository (phpipam/phpipam) — ~2,820 stars, created 2015-06-18 (GitHub REST API, fetched 2026-11-01); SolideInfo "Self Hosted IPAM Solutions" (updated ~90 days ago) — source-of-truth vs NMS misconception, REST/GraphQL automation; GetLabsDone NetBox site-management guide — region/site hierarchy, manual-entry cost; ttl255 pynetbox series — SDK history (noted as aging, v2-era examples).

Frequently asked questions

Is NetBox free?

Yes. NetBox is open source under the Apache-2.0 license, free to self-host with no user or feature limits in the community edition. NetBox Labs also offers a free NetBox Cloud plan for a hosted instance, plus paid Cloud and Enterprise tiers for teams that want support and managed operations.

Does NetBox automatically discover my network?

No. NetBox is a documentation and modeling system: it records the intended state you enter via the UI, CSV import, or API, and it does not poll or scan network devices on its own. Automatic discovery and reachability checks belong to monitoring and scanning tools, which can read from and write to NetBox through its API.

What database does NetBox use?

NetBox requires PostgreSQL (version 15 or newer per the current install docs) for its database and Redis (6.0 or newer) for caching and background task queuing. Both are non-negotiable dependencies — there is no SQLite or single-binary mode for production use.

Can I run NetBox on a small VPS?

For learning, yes: the Docker deployment runs the app, PostgreSQL, Redis, and a worker as a small set of containers, and a modest VPS handles a lab instance comfortably. For production with a large device inventory and heavy API automation, size the database host generously and put backups in place before the data becomes load-bearing.

How is NetBox different from a network monitor?

A network monitor observes live state — it polls devices and alerts when reality deviates. NetBox documents intended state — the design your automation and monitoring should be measured against. The two are complements: monitors detect drift, NetBox defines what "correct" looks like, and comparing the two is the core network-automation workflow.