Free and open source · Apache-2.0

Network diagrams from NetBox

NetDiagrams fills an 11-page draw.io network standard with your NetBox data. Run pip install netdiagrams, then netdiagrams, and get a drawing for every site, plus a report of what doesn't match. It works with the free, open-source NetBox you host yourself. No paid NetBox plan is needed.

Install it freeView on GitHub
Python 3.9+No dependenciesRead-onlyWorks with free NetBoxdraw.io or diagrams.net
$ netdiagrams NetBox URL: https://netbox.example.com API token (read-only is enough): •••••••• S01 Plant A ...... S01.drawio S01.drift.md S02 Plant B ...... S02.drawio S02.drift.md 2 sites drawn. Open the .drawio files in draw.io.
Short answer

To draw a network diagram from NetBox, install NetDiagrams with pip install netdiagrams and run netdiagrams. It asks for your NetBox URL and a read-only API token, then writes one draw.io drawing per site from a fixed 11-page standard, with every shape linked back to NetBox and a drift report of what doesn't match. It is free, open source (Apache-2.0) and works with the free NetBox you host yourself.

What NetBox fills in

Your drawing standard, filled from NetBox

A zoomed piece of the physical page of a sample plant, built from NetBox data.

Part of a physical network page built from NetBox, with numbered callouts1234
  1. 1Device name, model, management IP and serial come from the NetBox device.
  2. 2Port-channel members, speed, media and trunked VLANs come from NetBox cables and interfaces.
  3. 3HA pairs and stacks come from NetBox virtual chassis.
  4. 4The cable label on the drawing is the label in NetBox, which is the label on the real cable.
PLANT NETWORK SW1SW-NEWcore?SW1 (2)old FWPLC swSW-BunknownSW3VLAN TESThmispareSW1-final ask Dave which cable is the real uplink Network_Overview_FINAL_v3_revised.pdf · rev ? · date ?
Before: one rounded rectangle labeled PLANT NETWORK, rainbow cables, three switches called SW1, and a sticky note.
The same plant drawn to the NetDiagrams standard
After: the same site on the NetDiagrams logical page, with every VLAN in exactly one zone and its subnet, gateway and VRF filled from NetBox.

What it does

How it behaves

  • Free NetBox is enoughIt reads the NetBox REST API, so the free open-source edition on your own server works. A read-only API token is all it needs.
  • The layout stays exactly as drawnEvery page of the template comes out with the same shapes in the same places. Your site's names replace the template's.
  • Everything typed comes from NetBoxDevice fields, management IPs, serials, circuits, asset and link registers, VLAN tables per zone and title blocks.
  • Every item links to NetBoxClick a device, cable, VLAN, subnet or circuit in draw.io to open it in your NetBox.
  • Missing and extra, handledTemplate devices with no NetBox match are removed. Links missing from NetBox turn dashed. Unplaced devices wait in a tray.
  • Differences are reportedA drift report next to the drawing lists what doesn't match, so it doubles as a to-do list.
  • It only readsNetDiagrams sends GET requests to NetBox and never changes it. It never connects to your network devices.

The template

11 pages, one per audience

The bundled template is a complete network standard. Every device and cable shape already carries NetBox field names, so filling it is matching, not drawing. Bring your own template with --template.

  • Overview
  • Logical
  • Physical
  • Hardware and optics
  • Platform catalog
  • Wireless
  • Traffic flows
  • Failover
  • Multi-site WAN
  • Flow register
  • NetBox mapping
Part of the hardware and optics page of the sample template

NetBox topology view

NetBox topology view in draw.io

NetBox lists your devices, cables and VLANs, and topology plugins can draw them as a live graph. A graph of every cable answers "what is plugged into what", but it is not a drawing you can hand to an auditor, a plant manager or a vendor. NetDiagrams takes the same NetBox data and puts it on fixed sheets, one per question: an overview by security zone, a logical page with a VLAN table per zone, a physical page with every cable label, then hardware and optics, wireless, traffic flows, failover and the multi-site WAN.

  • The same layout on every run. Shapes stay where the template puts them, so this month's drawing can be laid over last month's and the differences stand out.
  • Every shape opens its NetBox record. Click a device, cable, VLAN, prefix or circuit in draw.io and it opens in your NetBox.
  • Big sites still fit. Repeated cells and closets are drawn once as a TYPICAL with a schedule row per copy, so a 3,000-device site prints on the same set of sheets.
  • Nothing is silently dropped. NetBox cables the template doesn't draw go on their own layer, and devices with no slot wait in a tray below the physical page.
  • No drawing yet? netdiagrams draft lays out a first draft for a site from its NetBox data, for you to tidy by hand.

It is a view you rebuild, not a live one. Run it again when NetBox changes and the drawing follows. Compare it with the NetBox topology plugins.

One drawing standard per industry

A plant groups its zones by Purdue level, a store keeps its payment zone apart, and a city keeps the police wing away from city hall. Each industry has its own template, stencils and fictional example site, picked with --profile. The example site is only a demo: the tool uses your NetBox unless you ask for the sample.

ProfileForField guide
manufacturingPlants, with Purdue levels, an industrial DMZ and production cellsBook 1 · Manufacturing
educationSchool districts and campusesBook 2 · Education
warehouseDistribution centers, cross-docks and 3PL sitesBook 3 · Warehousing and logistics
retailStores, with the payment zone kept apartBook 4 · Retail
officeOffices and branchesBook 5 · Offices
bankBanks and credit unions, with teller, wire and card zonesBook 6 · Banks and credit unions
municipalCities, towns and counties, with police (CJIS) and public Wi-Fi kept apartBook 7 · Local government
hotelHotels, with payments, guests and building systems kept apartBook 8 · Hotels and hospitality
corporateHeadquarters campuses and multi-site companies, with VRFs and a branch WANBook 9 · Corporate HQ and multi-site
dealershipCar dealerships, with F&I, the shop and the manufacturer's router kept apartBook 10 · Car dealerships

NetBox rack diagrams

NetBox already draws rack elevations, front and rear, from each device's rack and position, so NetDiagrams doesn't draw them again. It carries the rack and U position onto every device card and into the asset register, and shows the room path ("Main building › floor 1 › MDF-101") when your NetBox nests its locations. A site with more than one building or floor also gets a riser sheet: each building as a box, its floors stacked, the closets on each floor with their device counts, and the cables between them.

NetBox network documentation for an audit

An auditor asks two things of a network drawing: does it match the network, and who owns what is on it. A read-only export from NetBox answers both better than a hand-drawn file, because every value has a source.

  • A drift report beside every drawing. <site>.drift.md lists where the template and NetBox disagree, so it doubles as a to-do list.
  • A data quality sheet. It scores the site and lists what NetBox is missing. netdiagrams gaps writes the NetBox import files that fill those gaps.
  • Audit evidence per asset. An optional sheet shows owners, compliance scope, backups, patching, support contracts and monitoring for every device.
  • A copy that is safe to send. netdiagrams share removes IPs, serials, circuit IDs and NetBox links before a drawing goes to a vendor or insurer.

Still collecting the data? Start with the network documentation template, whose columns import straight into NetBox, or the free data collection worksheets.

Worked example: from NetBox to a drawing

  1. Install it and run netdiagrams doctor. It checks how your NetBox maps onto the template and changes nothing.
  2. Run netdiagrams netbox-setup --profile retail (or your industry). It writes numbered CSV files for the zone tags, device roles and custom fields the template reads. Import them with NetBox's Import buttons, or let --apply create only what is missing.
  3. Tag each VLAN and device with its zone, such as zone-cde for the payment VLANs. The NetBox import guide gives the order to load sites, racks, devices, cables and addresses.
  4. Run netdiagrams --profile retail. You get one .drawio file per NetBox site and a drift report next to each.
  5. Open the drawing in draw.io, read the drift report, fix the records in NetBox, and run it again. The physical page at the top of this page came out of exactly this loop.

The book behind the template

The tool fills the pages. The book explains them.

Draw Secure Manufacturing Network Diagrams walks through every sheet the tool draws: what each one is for, who reads it, and the rules that keep it true after the plant changes.

  • 1OverviewCh. 2 · The page your plant manager actually reads
  • 2LogicalCh. 4 · Zones on paper: the logical page
  • 3PhysicalCh. 5 · Cables are data, not decoration
  • 3bHardware and opticsCh. 6 · Optics, faceplates and the SFP drawer
  • 3dWirelessCh. 8 · Wireless without hand-waving
  • 4Traffic flowsCh. 9 · Draw the conversations
  • 5FailoverCh. 7 · Rings, pairs and what happens at 3 a.m.
  • 6Multi-site WANCh. 11 · More than one site
  • 7Flow registerCh. 10 · The flow register: your segmentation in writing
  • 8NetBox mappingCh. 12 · NetBox is the source, the drawing is the view
Get the book · $39 Read a free chapter
Cover: Draw Secure Manufacturing Network Diagrams

Limits

What the tool does not do

  • It doesn't change NetBox. It sends GET requests only. The one exception is netbox-setup --apply, which you run on purpose, and it only adds fields, tags and roles. It never edits what is there.
  • It doesn't touch your network. No scanning, no SNMP, no logins to switches, routers or firewalls. It talks to your NetBox and nothing else.
  • It doesn't poll or monitor. The drawing is as current as your NetBox on the day you ran it. Schedule a run if you want it fresh every week.
  • It keeps your token on your machine. After the first run the NetBox URL and token are saved in ~/.config/netdiagrams/config.json. In scripts and CI, pass NETBOX_URL and NETBOX_TOKEN instead. A read-only token is enough.
  • It doesn't read firewall rules. The flow register says what should be allowed between zones. Whether the firewall agrees is a separate check.

Weighing it against draw.io on its own, Graphviz or diagrams as code? See open source network diagram software compared.

Install

Install and run

$ pip install netdiagrams $ netdiagrams # one site, a chosen file name $ netdiagrams --site s07 -o s07.drawio # no NetBox yet? start from the sample or a blank set $ netdiagrams sample $ netdiagrams blank # add the zone fields, tags and roles the template uses $ netdiagrams netbox-setup

In scripts and CI, set NETBOX_URL and NETBOX_TOKEN. Full docs are in the README.

Need your data in NetBox first? Read How to Import a Plant Network into NetBox, free.