netgraph

Declare your network — switches, routers, hubs, computers, servers, cables, adapters, tunnels and patch panels — in a folder tree of YAML files, then render it as a network graph.

netgraph reads the tree, checks that the documents agree with each other, and draws the result as SVG, PNG, PDF, Graphviz DOT, Mermaid or JSON. It can also open the whole thing in a browser — netgraph web — where the YAML is edited on one side, drawn on the other, and every node and link answers a hover with its interfaces, addresses, VLANs and cabling. That page is driveable entirely from the keyboard, Ctrl-K for the command palette and ? for the list; see the bindings.

_{Produced from examples/home-lab with netgraph -i examples/home-lab render --layer l2 --title "home-lab — layer 2" -f svg -o docs/images/home-lab.svg.}

Nothing to install to look: every example inventory in this repository is published as a live diagram at https://blechschmidt.github.io/netgraph/demo/ — switch layers, filter by VLAN, hover a node for its interfaces and addresses. Those pages are the output of netgraph render -f html, not a demo built to look like it.

Status: early development (0.1.0). The schema, loader, validator, renderers and CLI work end to end; the schema may still change before 1.0. See §12 of the specification.

Network documentation rots because the diagram and the truth live in different places. The diagram is a drawing: nothing checks it, nothing regenerates it, and the day someone re-patches a link it starts lying.

netgraph puts the source of truth in reviewable, diffable YAML next to the rest of your infrastructure code, and generates the picture on demand. Because the files are structured rather than drawn, they can be checked: a cable that names a port which no longer exists is an error, not a line that happens to end in the wrong place.

Field names and value spaces follow RFC 8343 (ietf-interfaces), RFC 8344 (ietf-ip) and the IEEE 802.1Q bridge model, so an inventory stays comparable with what a device actually reports — see docs/yang-mapping.md.

netgraph needs Python 3.10 or newer.

pip install netgraph
pipx install netgraph        # or, to keep it out of your project environments
uv tool install netgraph     # same idea, faster

Check what you got — the version, and the Python and Graphviz it found:

netgraph --version
netgraph version --json      # the same report, for a bug report

From a checkout instead, when you are working on netgraph itself or want an unreleased change:

pip install -e .            # from a checkout
pip install -e '.[dev]'     # including the development tooling

The svg, png, pdf and html formats are produced by running the Graphviz dot binary, which is a system package rather than a Python one:

sudo apt install graphviz        # Debian / Ubuntu
sudo dnf install graphviz        # Fedora / RHEL
brew install graphviz            # macOS
choco install graphviz           # Windows

Check it with dot -V. The dot, mermaid and json formats are written by netgraph itself and need none of that, so if you only want DOT to feed into another tool you can skip the install.

Linux, macOS and Windows are all tested in CI. On Windows and macOS Graphviz is often installed without landing on PATH; netgraph looks in the usual install locations too, and NETGRAPH_DOT names the binary outright when that is not enough. Full instructions — including the PowerShell completion script and the .gitattributes an inventory kept in Git on Windows wants — are in docs/getting-started.md.

Or install nothing at all. The published image already has Graphviz in it, and runs the CLI, the live preview and the browser editor:

docker run --rm -v "$PWD:/inventory:ro" ghcr.io/blechschmidt/netgraph:latest validate

See docs/docker.md, which also covers docker-compose.yml for the two servers.

Five commands. init writes a small, valid inventory — devices, cables and a suite of assertions about them; edit it into your own network.

netgraph init my-network && cd my-network
$EDITOR devices/sw-office.yaml          # your switches, routers, hosts
netgraph validate                       # do the documents agree with each other?
netgraph test                           # do they still say what the network is for?
netgraph render -f svg -o network.svg   # draw it

The tree it writes looks like this — the folder a document sits in becomes its namespace, and nothing else about the layout carries meaning:

my-network/
├── netgraph.toml          # optional: default flags for this inventory
├── schema/                # JSON Schema, wired into your editor
├── devices/
│   ├── rtr-gw.yaml        # kind: router
│   ├── sw-office.yaml     # kind: switch
│   └── pc-alice.yaml      # kind: computer
└── cables/
    └── links.yaml         # which port is patched into which port

A device is a name, a kind and its interfaces; a cable is two endpoints:

apiVersion: netgraph.dev/v1alpha1
kind: switch
metadata:
  name: sw-office
spec:
  interfaces:
    - name: port1
      type: ethernet
      vlan: { mode: access, vid: 10 }
    - name: port2
      type: ethernet
      vlan: { mode: access, vid: 10 }

That inventory is checked in as examples/quickstart, so the following really is what it prints:

$ netgraph validate
no problems found
$ netgraph list devices
NAME               KIND      PORTS  ADDRESS           VLANS
-----------------  --------  -----  ----------------  -----
devices/pc-alice   computer      1  192.168.10.20/24  10
devices/rtr-gw     router        2  203.0.113.2/30    10
devices/sw-office  switch        2  -                 10

Point a cable at a port that does not exist and validate says so, with the file, the line and a rule id — which is the whole point. The step-by-step version of this, built by hand and explained line by line, is docs/getting-started.md.

Already have a network? netgraph import builds the first inventory from output you collect on the devices themselves — LLDP neighbours, ip -j addr show, or the cabling list you already keep — so it starts a diff away from correct instead of a weekend of typing:

lldpctl -f json > collected/"$(hostname -s)".lldp.json    # on each device
netgraph import -o my-network collected/*.json

Once the tree exists, netgraph drift reads the same captures the other way round — the inventory becomes an assertion about the network, and the command reports where reality disagrees. What a capture cannot see is reported as unobserved rather than as a deletion, so a partial capture never reads as the network having been dismantled, and --fail-on drift makes it a gate for a nightly job.

netgraph [GLOBAL OPTIONS] COMMAND [OPTIONS] [ARGS]. The inventory is named once, with the global -i/--inventory, and defaults to the current directory. Data goes to stdout and commentary to stderr, so netgraph render -f json | jq and netgraph validate > report.txt both do what they look like they do.

Every flag of every command, the global options and the exit codes: docs/commands/. Those tables are generated from the CLI itself and checked by the test suite, so they cannot drift from the code.

The files describe the network once; each command asks something different of them.

Two of them are worth seeing. Nothing in the YAML declares a subnet: the layer-3 view and list subnets both derive the prefixes from the addresses the interfaces carry, which is why they cannot disagree with the configuration,

$ netgraph -i examples/home-lab list subnets
SUBNET            IP  ADDRESSES  ELEMENTS  VLANS
----------------  --  ---------  --------  -----
192.0.2.1/32       4          1         1  -
192.168.10.0/24    4          7         7  10
203.0.113.0/30     4          1         1  -
2001:db8::1/128    6          1         1  -
2001:db8:10::/64   6          5         5  10

and netgraph path traces the route two hosts in different sites actually take, naming the ingress and egress port at every hop:

$ netgraph -i examples/campus path pc-north-01 pc-south-01
sites/north/hosts/pc-north-01 -> sites/south/hosts/pc-south-01: 2 paths
  source       sites/north/hosts/pc-north-01  [computer]
  destination  sites/south/hosts/pc-south-01  [computer]
  layer        3, routed (ipv4)
  showing      the shortest; pass --all for the rest
  note         no layer-2 path: the two elements are in no common broadcast domain, so the trace looked for a routed one
...

docs/README.md is the index, with an "if you want to X, read Y" table over the whole set. The pages a new reader wants first:

Five complete, self-consistent inventories live under examples/ — from the three-device quickstart to a 22-device campus with nested namespaces, a five-tunnel overlay with VXLAN inside IPsec, and a patch room with two racks of structured cabling. All of them validate clean with no suppressions, and the test suite renders them on every commit, so they stay executable rather than aspirational.

$ netgraph -i examples/patch-room validate
no problems found

Everything the CLI does is available from Python: load_tree reads a folder into an Inventory, validate returns findings, build_graph resolves the topology, and the renderers are pure functions of the graph. See Using it as a library.

CONTRIBUTING.md has the dev setup and the gates (ruff, ruff format, mypy, pytest with a coverage floor), plus recipes for adding a validation rule or a renderer. docs/architecture.md is the ten-minute orientation: the pipeline is load_tree → validate → build_graph → filter/aggregate → renderers, and each stage's invariants are written down.

MIT