# WireViz: YAML-Defined Wiring Harnesses That Render Themselves > WireViz turns a plain-text YAML description of connectors, cables and pinouts into an SVG diagram and a bill of materials. It is a documentation tool for people building harnesses by hand, not a schematic capture program. **wireviz/WireViz** — Easily document cables and wiring harnesses. - Repository: https://github.com/wireviz/WireViz - Stars: 5,290 · Forks: 318 - Language: Python - License: GPL-3.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/wireviz-wireviz ## The problem WireViz solves: harness documentation that lives in text A wiring harness is a physical object with a bill of materials: connectors, wire gauges, lengths, colours and a pin-to-pin mapping. Teams usually record that in a spreadsheet or a drawing, and both drift. The spreadsheet cannot draw, and the drawing cannot be diffed. WireViz targets that gap. Its input is a YAML file, which the README describes as fully text based, human readable and easy to version control, with no special editor required. The output is a rendered diagram plus a generated BOM. The README is explicit about scope: WireViz is not designed to represent the complete wiring of a system, and its main aim is to document the construction of individual wires and harnesses. That boundary matters more than any feature list. It is a harness documentation tool, not an EDA package. ## How a WireViz file becomes a diagram and a BOM A WireViz file has three top-level keys. connectors declares the endpoints and their pin labels. cables declares the wire bundles, their gauge, length, wire count, colour code and whether they are shielded. connections is a list of groups, and each group is a list of mappings from a component to the pins or wires involved. The README's demo01 shows the shape. Connector X1 is a female D-Sub with pin labels DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI. Connector X2 is a female Molex KK 254 with GND, RX, TX. Cable W1 is 0.25 mm2, 0.2 long, three wires, DIN colour code, shielded. The connections block then pairs pins positionally: ```yaml connections: - - X1: [5,2,3] - W1: [1,2,3] - X2: [1,3,2] - - X1: 5 - W1: s ``` The first group wires X1 pins 5, 2 and 3 to W1 wires 1, 2 and 3, and those to X2 pins 1, 3 and 2. The second group connects X1 pin 5 to the shield of W1, referenced as s. From this, WireViz builds a GraphViz graph, renders it, and derives the BOM. Colour schemes come from named standards rather than free text: the README lists DIN 47100, IEC 60757, the 25 Pair Color Code and the TIA/EIA 568 A/B subset used in CAT-5/6. Gauges can be written in mm2 or AWG, with optional automatic conversion between the two. ## Installing WireViz and rendering your first harness WireViz needs Python 3.7 or later, and it needs GraphViz installed separately. The README points to the GraphViz download page for OS-specific instructions, and notes that Ubuntu 18.04 LTS users in particular may need to install Python 3.7 or above, since that release ships Python 3.6 as the system Python. The release install is one command: ```bash pip3 install wireviz ``` To run the development branch instead, the README gives a clone, a checkout of dev, and an editable install: ```bash git clone cd git checkout dev pip3 install -e . ``` Running the tool takes a path to a YAML file: ```bash wireviz ~/path/to/file/mywire.yml ``` Depending on the options specified, the README says this produces some or all of mywire.gv (the GraphViz output), mywire.svg, mywire.png, mywire.bom.tsv and mywire.html, an HTML page with the diagram and BOM embedded. Wildcards are supported, so `wireviz ~/path/to/files/*.yml` processes several files at once. Run `wireviz --help` for the output format options. The repository ships examples/demo01.yml and examples/demo02.yml with their matching .svg, .png, .bom.tsv and .html outputs, so you can compare your render against a known-good one. ## Where WireViz stops being the right tool The connections syntax is positional, and that is the main friction. In demo01, X1 pin 5 connects to W1 wire 1 and X2 pin 1 because all three sit at index zero of their respective lists. Reordering a cable's wire list silently changes which pins connect. For a two-wire cable this is fine. For a 60-pin harness it is a place where a careless edit produces a diagram that looks correct and is not. The scope limit is the second constraint. A system-level schematic, with power distribution, grounding strategy and inter-harness relationships, is outside what the README claims to do. If that is what you need, WireViz will not replace it. The stability caveat is the third. The README's status section says this is very much a work in progress, and that source code, API, syntax and functionality may change wildly at any time. The setup.py classifiers list Development Status as 4 - Beta. The most recent release in the repository is v0.4.1 from 2024-07-13. The last push to the default branch was on 2026-06-06, so work has continued since that release, but the released version is what you get from pip3 install wireviz. Treat the YAML schema as something to pin alongside your files rather than a frozen contract. ## WireViz compared with hand-drawn diagrams and generic diagram tools The obvious alternative is drawing the harness in a vector editor or a general diagramming tool. Those give you total layout control, and they give you a binary or XML file that is painful to review. A WireViz file is a short YAML document, so a pull request shows exactly which pin moved. The trade-off runs the other way too: you do not control the layout. GraphViz decides where the connectors sit, and the README offers easy autorouting for 1-to-1 wiring rather than a layout editor. If a specific visual arrangement is a requirement, a drawing tool wins. The other alternative is a full ECAD or schematic capture package. Those model nets, symbols and footprints across a whole design, and they carry the price and learning curve that implies. WireViz deliberately does less: connectors, cables, connections, BOM. The README's own framing is the honest summary. For documenting the construction of one harness, a text file plus a render command is a smaller commitment than a schematic toolchain. ## Licence and the cost of keeping WireViz files current WireViz is GPL-3.0, and setup.py declares license="GPLv3" with the matching OSI classifier. That is a copyleft licence. If you install it as a command-line tool and use it to document your own hardware, the licence governs the tool, not your YAML. If you intend to embed WireViz in something you distribute, or to ship a modified version, the copyleft terms apply to that distribution. This is a description of the licence identifier, not legal advice; read the LICENSE file and talk to someone qualified if your use is not obviously internal. Upgrade cost is mostly the schema. Because the README warns that syntax may change wildly, an upgrade can require editing YAML files. Keeping the examples directory from a matching release is the cheapest way to check a file after upgrading: render it and compare against the shipped .svg and .bom.tsv. The dependency list is short (click, pyyaml, pillow, graphviz), which limits the surface that can break, but GraphViz itself is an external binary you install and maintain separately. ## Conclusion Adopt WireViz if your harnesses are documented in spreadsheets or hand-drawn and you want them in version control as text. Do not adopt it if you need full system schematics, since the README states it is not designed to represent the complete wiring of a system, or if you need a stable syntax, since the project's own status note warns that source code, API, syntax and functionality may change wildly at any time. Before committing, verify that GraphViz is installed and reachable on your PATH, that a demo file renders end to end, and that the GPL-3.0 licence fits how you intend to distribute the tool. ## FAQ ### What is WireViz? WireViz is a tool for documenting cables, wiring harnesses and connector pinouts. It takes YAML input and produces graphical output such as SVG and PNG via GraphViz, along with an automatically generated bill of materials. ### How to install WireViz? Install GraphViz first, since WireViz requires it, then run pip3 install wireviz. Python 3.7 or later is required, and the README notes Ubuntu 18.04 LTS users may need to install a newer Python separately. ### What are the color codes in WireViz? The README lists DIN 47100, IEC 60757, the 25 Pair Color Code and the TIA/EIA 568 A/B subset used in CAT-5/6 cabling. WireViz understands the IEC 60757 abbreviations such as BK for black and RD for red, and also allows custom schemes. ### how to use wireviz Write a YAML file with connectors, cables and connections sections, then run wireviz on it, for example wireviz ~/path/to/file/mywire.yml. The command produces some or all of a .gv, .svg, .png, .bom.tsv and .html file depending on the options specified. ## Sources - [Issues](https://github.com/wireviz/WireViz/issues) - [License: GPL-3.0](https://github.com/wireviz/WireViz/blob/master/LICENSE) - [README](https://github.com/wireviz/WireViz/blob/master/README.md) - [Releases](https://github.com/wireviz/WireViz/releases) - [wireviz/WireViz on GitHub](https://github.com/wireviz/WireViz) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wireviz-wireviz