netviz

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.

netviz 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 — netviz 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 netviz -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/netviz/demo/ — switch layers, filter by VLAN, hover a node for its interfaces and addresses. Those pages are the output of netviz render -f html, not a demo built to look like it.

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

Why

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.

netviz 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.

Installation

netviz needs Python 3.10 or newer.

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

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

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

From a checkout instead, when you are working on netviz itself or want an unreleased change. netviz develops with uv: uv.lock is committed, so this installs the exact versions every CI job runs against rather than whatever resolves today.

uv sync                     # runtime dependencies, from uv.lock
uv sync --extra dev         # including the development tooling
uv run netviz --version     # or activate .venv and drop the prefix

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 netviz 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; netviz looks in the usual install locations too, and NETVIZ_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/netviz:main validate

main is the tip of the default branch, rebuilt on every push. No version has been released yet, so there is no latest to pull — see docs/docker.md for the full tag list, which also covers docker-compose.yml for the two servers.

Quickstart

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

netviz init my-network && cd my-network
$EDITOR devices/sw-office.yaml          # your switches, routers, hosts
netviz validate                       # do the documents agree with each other?
netviz test                           # do they still say what the network is for?
netviz 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/
├── netviz.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: netviz.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:

$ netviz validate
no problems found
$ netviz 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? netviz 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
netviz import -o my-network collected/*.json

Once the tree exists, netviz 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.

The commands

netviz [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 netviz render -f json | jq and netviz 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.

One inventory, several questions

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,

$ netviz -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 netviz path traces the route two hosts in different sites actually take, naming the ingress and egress port at every hop:

$ netviz -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
...

Where to go next

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:

Examples

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.

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

As a library

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

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.

License

MIT