Graphviz Python Interface

Common errors

• 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`.

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

• 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

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