Graphviz Python Interface

0.21 · active · verified Sun Mar 29

The `graphviz` library provides a simple pure-Python interface for generating and rendering graph descriptions in the DOT language, which is used by the Graphviz graph-drawing software. It allows users to programmatically create directed and undirected graphs, add nodes and edges, apply attributes for styling, and then render them into various output formats (e.g., PDF, PNG, SVG). The current version is 0.21, and the project maintains an active release cadence with regular updates and Python version support.

Warnings

breaking The `graphviz` Python package is a wrapper for the external Graphviz command-line tools. It is crucial to install the Graphviz software separately on your operating system and ensure its executables (e.g., `dot`, `neato`) are accessible in your system's PATH environment variable. Failure to do so will result in `graphviz.exceptions.ExecutableNotFound` errors.
Fix: Install the native Graphviz software for your OS (e.g., via `apt`, `dnf`, Homebrew, or official installers) and verify that its `bin` directory is correctly added to your system's PATH. Test by running `dot -V` in your terminal. Restart any IDEs or terminals after updating PATH.
breaking Python 3.8 support was dropped in `graphviz` version 0.21. Previous versions (e.g., 0.20.2) dropped Python 3.7 support. Ensure your Python environment meets the minimum version requirement (currently Python 3.9+ for v0.21).
Fix: Upgrade your Python environment to Python 3.9 or higher if you intend to use `graphviz` version 0.21 or newer. Check the changelog for specific version compatibility if targeting older `graphviz` releases.
gotcha Handling backslash escapes and special characters (like quotes) within DOT language strings, especially for `label` attributes, can be tricky. Prior to version 0.14, using `\"` for a literal quote could break the internal quoting mechanism. Raw string literals (`r'...'`) are often recommended to simplify backslash handling.
Fix: Use raw string literals (e.g., `label=r'hello\nworld'`) for strings containing backslashes. For literal quotes, simply use `label='"'` as of version 0.14+, which handles the escaping automatically. Refer to the 'Backslash escapes' section in the official user guide for detailed examples.
gotcha Default graph layouts can sometimes result in overlapping nodes or edges, or an undesirable ordering. This is often due to the graph layout algorithms trying to optimize for compactness or other factors without specific user guidance.
Fix: Utilize DOT attributes like `overlap`, `nodesep`, `ranksep`, `rankdir`, `splines`, or explicitly set node ranks to fine-tune the layout. For complex layouts, consider creating invisible nodes/edges to guide the layout engine or using subgraphs.

Install

pip install graphviz Install Python package
sudo apt install graphviz Install Graphviz (Debian/Ubuntu)
sudo dnf install graphviz Install Graphviz (Fedora/RHEL)
brew install graphviz Install Graphviz (macOS Homebrew)
choco install graphviz Install Graphviz (Windows Chocolatey)

Imports

Graph
```
from graphviz import Graph
```
For creating undirected graphs.
Digraph
```
from graphviz import Digraph
```
For creating directed graphs.
graphviz
```
import graphviz
```
Commonly used for direct access to Graph and Digraph via `graphviz.Graph` or `graphviz.Digraph`.

Quickstart

This example demonstrates how to create a directed graph, add nodes and edges, and then render it to a PNG file which is automatically opened for viewing. The `Digraph` class is used for directed graphs, and `Graph` for undirected ones. The `render()` method saves the graph to a file and, with `view=True`, opens it using the system's default viewer.

import graphviz

dot = graphviz.Digraph('MyGraph', comment='A Simple Directed Graph')

# Add nodes
dot.node('A', 'Node A')
dot.node('B', 'Node B')
dot.node('C', 'Node C')

# Add edges
dot.edge('A', 'B', label='connects')
dot.edge('B', 'C', label='leads to')
dot.edge('C', 'A', label='cycles back')

# Render and view the graph
dot.render('my_simple_graph', view=True, format='png')

view raw JSON →