Graphviz Python Interface

0.21 verified Tue May 12 auth: no python install: verified

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.

pip install graphviz

Common errors

error ModuleNotFoundError: No module named 'graphviz' ↓

cause The Python `graphviz` package is not installed in the active Python environment or the environment in which you are running your code.

fix

Install the graphviz Python package using pip: pip install graphviz.

error graphviz.backend.ExecutableNotFound: failed to execute ['dot', '-Tsvg'], make sure the Graphviz executables are on your systems' PATH ↓

cause The Python `graphviz` library is a wrapper around the Graphviz system software, and this error occurs when the underlying Graphviz executable (like `dot`) is not installed on your system or its location is not added to your system's PATH environment variable.

fix

1. Install the Graphviz system software from the official Graphviz website (graphviz.org/download/). 2. Add the bin directory of your Graphviz installation to your system's PATH environment variable. For example, on Windows, this might be C:\Program Files\Graphviz\bin or C:\Program Files (x86)\Graphviz\bin. On Linux/macOS, ensure it's in a standard PATH location like /usr/local/bin or ensure it's installed via a package manager (sudo apt-get install graphviz for Debian-based systems, brew install graphviz for macOS). 3. Restart your terminal or IDE to ensure the updated PATH is recognized. Alternatively, you can set the GRAPHVIZ_DOT environment variable in your script to the exact path of the dot executable.

error graphviz.backend.CalledProcessError: Command '['dot', '-Tpng']' returned non-zero exit status 1 ↓

cause This error indicates that the `dot` executable was found and executed, but it failed to process the graph description or generate the output, often due to invalid DOT language syntax in your graph definition, or issues with the Graphviz installation itself, such as missing dependencies for a specific output format.

fix

1. Review your DOT graph source code for any syntax errors or inconsistencies. Print dot.source to inspect the generated DOT code. 2. Try rendering to a different output format (e.g., SVG, PDF) to see if the issue is specific to PNG or the viewer for that format. For example: dot.format = 'svg'. 3. Ensure your Graphviz system installation is complete and healthy by running dot -V in your terminal and checking for any warnings or errors. For complex diagrams, ensure all necessary Graphviz tools/layout engines are installed (e.g., graphviz-dev on Linux).

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

sudo apt install graphviz

sudo dnf install graphviz

brew install graphviz

choco install graphviz

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.09s 18.2M

3.10 alpine (musl) - - 0.08s 18.2M

3.10 slim (glibc) wheel 1.5s 0.06s 19M

3.10 slim (glibc) - - 0.06s 19M

3.11 alpine (musl) wheel - 0.14s 20.1M

3.11 alpine (musl) - - 0.16s 20.1M

3.11 slim (glibc) wheel 1.6s 0.13s 21M

3.11 slim (glibc) - - 0.12s 21M

3.12 alpine (musl) wheel - 0.12s 11.9M

3.12 alpine (musl) - - 0.12s 11.9M

3.12 slim (glibc) wheel 1.4s 0.12s 12M

3.12 slim (glibc) - - 0.12s 12M

3.13 alpine (musl) wheel - 0.11s 11.7M

3.13 alpine (musl) - - 0.11s 11.6M

3.13 slim (glibc) wheel 1.5s 0.13s 12M

3.13 slim (glibc) - - 0.11s 12M

3.9 alpine (musl) wheel - 0.07s 17.7M

3.9 alpine (musl) - - 0.08s 17.7M

3.9 slim (glibc) wheel 1.8s 0.07s 18M

3.9 slim (glibc) - - 0.07s 18M

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 last tested: 2026-04-24

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')