pydotplus

2.0.2 · maintenance · verified Wed Apr 15

PyDotPlus is a Python interface to Graphviz's Dot language, acting as an improved version of the original `pydot` project. It allows users to programmatically create, read, and manipulate graphs defined in the DOT language and render them into various image formats using Graphviz. The current version is 2.0.2, with its last release in December 2014, indicating a maintenance rather than active development cadence.

Warnings

breaking Graphviz must be installed separately and its executables must be in your system's PATH environment variable. Failure to do so will result in `pydotplus.graphviz.InvocationException: GraphViz's executables not found` when attempting to render graphs.
Fix: Download and install Graphviz from https://graphviz.org/download/. After installation, add the path to its 'bin' directory (e.g., `C:\Program Files\Graphviz\bin` on Windows or `/usr/local/bin/` on macOS/Linux if installed via Homebrew/apt) to your system's PATH environment variable. Restart your terminal/IDE after modifying PATH.
gotcha When running on Windows, if the Graphviz installation path contains spaces (e.g., `C:\Program Files (x86)\Graphviz...`), you might encounter `InvocationException: 'C:\Program' is not recognized as an internal or external command`. This is due to how subprocesses handle unquoted paths.
Fix: Ensure the Graphviz installation path added to your PATH environment variable is properly quoted if it contains spaces, or ideally, install Graphviz to a path without spaces (e.g., `C:\Graphviz`). Alternatively, some users report success by modifying `pydotplus`'s internal `graphviz.py` to add quotes around executable paths, but this is a hacky solution.
gotcha Confusion between `pydot` and `pydotplus` is common. `pydotplus` was created as an actively maintained fork to address issues in `pydot`, particularly Python 3 compatibility and `pyparsing` version support, during a period when `pydot` development was stalled.
Fix: If starting a new project or migrating, prefer `pydotplus` for better Python 3 compatibility. Ensure you only install one of them to avoid potential conflicts in import paths or runtime behavior, although they typically import as `pydotplus` and `pydot` respectively.

Install

pip install pydotplus Install stable version

Imports

Dot
wrong:
```
from pydotplus import Dot
```
correct:
```
import pydotplus
graph = pydotplus.Dot()
```
While direct import is possible, `import pydotplus` and using `pydotplus.Dot()` is the most common and robust pattern.

graph_from_dot_data

import pydotplus
graph = pydotplus.graph_from_dot_data(dot_string)

Quickstart

This quickstart demonstrates how to create a simple directed graph with nodes and edges using `pydotplus` and then attempts to render it to a PNG image. It also includes an example of loading a graph from a DOT string. **Crucially, for the rendering step to succeed, Graphviz must be installed on your system and its `bin` directory must be added to your system's PATH environment variable.**

import pydotplus
import os

# Create a directed graph
graph = pydotplus.Dot(graph_type='digraph')

# Add nodes
node_a = pydotplus.Node("A", style="filled", fillcolor="red")
node_b = pydotplus.Node("B", style="filled", fillcolor="green")
node_c = pydotplus.Node("C", style="filled", fillcolor="blue")

graph.add_node(node_a)
graph.add_node(node_b)
graph.add_node(node_c)

# Add edges
edge_ab = pydotplus.Edge("A", "B", label="connects")
edge_bc = pydotplus.Edge("B", "C", arrowhead="open")

graph.add_edge(edge_ab)
graph.add_edge(edge_bc)

# Try to save the graph to a file
try:
    # This requires Graphviz to be installed and its executables in the system PATH
    output_file = "simple_graph.png"
    graph.write_png(output_file)
    print(f"Graph '{output_file}' created successfully.")
except pydotplus.graphviz.InvocationException as e:
    print(f"Error: Graphviz executables not found or not in PATH. {e}")
    print("Please install Graphviz (https://graphviz.org/download/) and add its 'bin' directory to your system's PATH environment variable.")
    print("For example, on Windows: ';C:\Program Files (x86)\Graphviz2.38\bin' should be added to PATH.")
    print("On Linux/macOS, ensure Graphviz is installed via package manager and 'dot' command is accessible.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# Example of loading from DOT data
dot_data = "digraph { A -> B; B -> C; }"
loaded_graph = pydotplus.graph_from_dot_data(dot_data)
# loaded_graph.write_svg("loaded_graph.svg") # Uncomment to save

view raw JSON →