# netbox-topology-views draws its maps from the cables you already recorded

> netbox-topology-views is a NetBox plugin that renders a topology map from the cable records in your source of truth, with filters on name, site, tag and device role, coordinate saving so the layout survives, and export to draw.io XML or PNG. The repository is Apache 2.0 licensed, ships as a Python package, and its version numbers track the NetBox release it supports, which is both its most useful feature and its most awkward one.

**netbox-community/netbox-topology-views** — A netbox plugin that draws topology views 

- Repository: https://github.com/netbox-community/netbox-topology-views
- Stars: 1,105 · Forks: 107
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/netbox-community-netbox-topology-views

## The cables are the input

The plugin's premise is that the topology already exists somewhere, and that somewhere is NetBox. It creates topology views and maps from your devices in NetBox, and the connections are based on the cables you created in NetBox. That is the whole architectural idea, and it is why the plugin is small, because the hard work of knowing what connects to what has already been done by the cabling records, and the plugin's job is to lay the result out and let you adjust it. The audience is a network engineer whose cabling data is in good shape, and the alternative approaches, drawing the map in a diagram tool by hand, mean the diagram and the source of truth drift apart within a month. The preview images in the repository show the same topology rendered in a light and a dark mode, and the feature list adds filtering on name, site, tag and device role, which is what makes a map of a few hundred devices usable rather than a hairball.

## Installing it takes a pip install and a configuration entry

The plugin is a Python package, so the install runs inside the NetBox virtual environment. The documented steps are:

```bash
source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
pip3 install netbox-topology-views
python3 manage.py migrate netbox_topology_views
python3 manage.py collectstatic --no-input
```

The migrate and collectstatic steps are the standard ones for a NetBox plugin, and the collectstatic run is what publishes the plugin's static files. The plugin then has to be enabled in your configuration.py with the PLUGINS list set to the plugin's module name, PLUGINS = ["netbox_topology_views"], and NetBox has to be restarted with systemctl restart netbox. Two installation details are specific to this plugin. For Docker deployments there is a separate note pointing at the netbox-docker wiki on using NetBox plugins, and for the container build you need to add a line creating the image folder, RUN mkdir -p /opt/netbox/netbox/static/netbox_topology_views/img, to the Dockerfile-Plugins file. And if you want the plugin to survive future NetBox upgrades, you add the package to a local_requirements.txt file in the NetBox root directory alongside requirements.txt, so the upgrade process reinstalls it.

## The version table is the upgrade contract

The versions section is a table mapping a NetBox version to the plugin version that supports it, and the note above it is the important part. If the version of NetBox is not listed there, the plugin will most likely not work, and the instruction is to remove the plugin if you want to update NetBox before the plugin has released an update for that NetBox version. The table runs from NetBox 4.5.X to plugin v4.5.1, 4.4.X to v4.4.0, 4.3.X to v4.3.0, then the point releases 4.2.1 and 4.2.0 mapping to themselves, 4.1.X to v4.1.0 and 4.0.X to v4.0.0, and then the older lines where the numbering diverges, with NetBox 3.7.0 taking plugin v3.9.0, 3.6.4 taking v3.8.1, 3.6.0 taking v3.7.0 and 3.5.0 taking v3.6.2. The pattern in the old lines is that the plugin version ran ahead of the NetBox version, which is how a plugin keeps up with several NetBox releases at once. The current release is v4.7.0, published on 2026-09-18, and the last push was on 2026-10-15 on the develop branch.

## Coordinates, filters and export

Three capabilities carry the plugin. Coordinates are what make a map usable, because a layout you can save and come back to is a diagram, and a layout recalculated on every visit is a drawing. The filter page is where you narrow the view, with options to show unconnected devices and to show cables, and the individual options can have a default value per user assigned directly in the plugin, with the default overridden on the filter page. Export is the third, and it is broader than a screenshot. The plugin can export to XML, for draw.io or diagrams.net, or to PNG, and the XML route is the one that matters, because a draw.io file is editable, so the exported map can be dropped into a document, annotated and checked back in, which closes the loop the plugin opened by reading the cabling data. The remaining options must be configured in the PLUGINS_CONFIG section of netbox/configuration.py, with the static_image_directory, allow_coordinates_saving and always_save_coordinates keys.

## The coordinates custom field is on its way out

The coordinate storage has a history, and the history is visible in the documentation. The original mechanism is a NetBox custom field named coordinates, created for dcim > device and Circuits > circuit with the type text, and the values are stored as X;Y. You are told to set the field to UI visibility Hidden and let the plugin manage it in the background, and to read the configure chapter to set allow_coordinates_saving to True, with always_save_coordinates as the option that makes saving the default rather than optional. The deprecation notice is explicit, that the custom field coordinates is deprecated and will be removed in the future, and that you should use Coordinate Groups instead. And the values in the old custom field are not converted automatically, so the documentation gives a manual procedure, which is a good example of how a migration like this is usually done in practice.

## Converting to Coordinate Groups by dragging a box

The manual conversion is a UI procedure rather than a script, and it is worth reading because it shows what the plugin can and cannot do. Navigate to Topology and then Filters, select Show Unconnected and Show Cables, and leave all the other filter settings alone, because the point is to have every entry displayed. Click Search and wait for the results. Then select all the nodes, which the documentation says can be done by holding down the Shift key and dragging a frame around all the icons with the left mouse button, and drag the selection a tiny bit to the side, which causes all the coordinates for all devices to be stored in the default group. There is a hint attached, that you should not wait too long after clicking an icon before dragging, because if the mouse button is held too long before the drag starts the selection is reset. Storing the values takes some time depending on the number of devices, so the advice is to be patient and check the Coordinates tab to make sure everything was stored. Once that is done it is safe to delete the custom field.

## Custom images, and the shape of the plugin

The last configuration area is images. To change the image associated with a device you use the Images page, which allows you to map a device role with an image found in the NetBox static directory, and that directory is the one named by the static_image_directory plugin config, which defaults to netbox_topology_views/img and must be within STATIC_ROOT. The repository layout is what you would expect for a NetBox plugin, with the netbox_topology_views/ package, a netbox-plugin.yaml manifest, a setup.py, requirements.txt, a MANIFEST.in, a SECURITY.md, a doc/ directory holding the images used in the README, and a dev_setup/ directory for local development. The dependencies are small, with djangorestframework and django-filter, and black in the requirements list, which tells you the project formats with black. The packaging is plain setuptools with no install_requires of its own, since the plugin runs inside NetBox's own environment and picks up what NetBox already provides.

## Conclusion

netbox-topology-views is worth installing if your cabling data in NetBox is already accurate and you want a picture of it, because the plugin does not ask you to describe the topology again, it reads the connections you have already recorded and draws them. It is the wrong tool if you are trying to design a network rather than document one, and the wrong tool for a NetBox instance you do not control the upgrade schedule of, because the version matrix means each NetBox release needs a matching plugin release. Before you install it, check the version table against the NetBox version you are on, because the documentation says a plugin will most likely not work on an unlisted NetBox version, and decide whether you want coordinates saved at all, since the custom field route is deprecated in favour of Coordinate Groups and the conversion is a manual procedure.

## FAQ

### How do I install netbox-topology-views?

Activate the NetBox virtual environment, then run pip3 install netbox-topology-views, python3 manage.py migrate netbox_topology_views and python3 manage.py collectstatic --no-input. Then add the plugin to the PLUGINS list in netbox/configuration.py, restart NetBox, and for Docker builds create the image folder with a mkdir line in the Dockerfile-Plugins file.

### Which NetBox version does the plugin support?

The README maps NetBox versions to plugin versions, with 4.5.X using v4.5.1, 4.4.X using v4.4.0, 4.3.X using v4.3.0, and the point releases 4.2.1, 4.2.0, 4.1.X and 4.0.X matching. The note says that if the NetBox version is not listed the plugin will most likely not work, and that it should be removed before updating NetBox.

### How does the plugin know what is connected to what?

The connections are based on the cables you created in NetBox, so the plugin reads the cabling records rather than asking you to describe the topology. You can then filter the view on name, site, tag and device role, and export the result to XML for draw.io or to PNG.

### How are the node coordinates stored, and what is deprecated?

Coordinates were stored in a NetBox custom field named coordinates, with the values as X;Y, and that custom field is deprecated in favour of Coordinate Groups. Saving requires allow_coordinates_saving to be set to True in PLUGINS_CONFIG, and always_save_coordinates makes it the default. Values in the old field are not converted automatically and the README gives a manual conversion procedure.

## Sources

- [Issues](https://github.com/netbox-community/netbox-topology-views/issues)
- [License: Apache-2.0](https://github.com/netbox-community/netbox-topology-views/blob/develop/LICENSE)
- [netbox-community/netbox-topology-views on GitHub](https://github.com/netbox-community/netbox-topology-views)
- [README](https://github.com/netbox-community/netbox-topology-views/blob/develop/README.md)
- [Releases](https://github.com/netbox-community/netbox-topology-views/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/netbox-community-netbox-topology-views