Install & Compatibility
Where this runs
tested against v4.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.058s · 19MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.052s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dot
✓ import pydot
graph = pydot.Dot(...)
Node
✓ import pydot
node = pydot.Node(...)
Edge
✓ import pydot
edge = pydot.Edge(...)
This quickstart demonstrates how to create a directed graph using pydot, add nodes with custom styles, connect them with edges, and save the resulting visualization as a PNG image. It includes basic error handling for common Graphviz executable issues.
import pydot
import os
# Ensure Graphviz dot executable is found. On some systems or environments,
# pydot might not find it automatically. This is for demonstration; usually,
# ensuring Graphviz is in PATH is enough.
# You might need to set this if Graphviz is installed in a non-standard location.
# For example, on Windows: os.environ["PATH"] += os.pathsep + 'C:/Program Files/Graphviz/bin'
graph = pydot.Dot('my_graph', graph_type='digraph')
node_a = pydot.Node('A', style='filled', fillcolor='red')
node_b = pydot.Node('B', style='filled', fillcolor='blue')
node_c = pydot.Node('C')
graph.add_node(node_a)
graph.add_node(node_b)
graph.add_node(node_c)
graph.add_edge(pydot.Edge(node_a, node_b, label='edge_ab'))
graph.add_edge(pydot.Edge(node_b, node_c, label='edge_bc', color='green'))
graph.add_edge(pydot.Edge(node_c, node_a, label='edge_ca', arrowhead='vee'))
# Save the graph to a PNG file
try:
graph.write_png('output_graph.png')
print("Graph saved to output_graph.png")
except pydot.InvocationException as e:
print(f"Error generating graph: {e}")
print("Make sure Graphviz is installed and its 'dot' executable is in your system PATH.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingPydot relies on Graphviz for rendering graphs. If Graphviz is not installed separately on your system (beyond `pip install pydot`) and its `dot` executable is not in your system's PATH, pydot will raise an `OSError` (specifically `FileNotFoundError`) when attempting to execute Graphviz commands. Note that `pydot.InvocationException` might not be defined or raised directly in some `pydot` versions, leading to an `AttributeError` if caught explicitly.fixInstall Graphviz on your operating system (e.g., `sudo apt install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS) and ensure its binaries are accessible via your system's PATH environment variable. When handling errors related to Graphviz execution, it is more robust to catch `OSError` or `FileNotFoundError` rather than `pydot.InvocationException`, as the latter may not be defined or directly raised depending on the `pydot` version.
affects: All versions of pydot
gotchaUsing colons (:) directly in node names or edge labels without proper escaping can lead to Graphviz syntax errors when rendering, resulting in `InvocationException`.fixEscape colons with a backslash (`\:`) or enclose the entire label/name in quotes if it contains special characters, especially colons, to ensure Graphviz parses it correctly. For example, `pydot.Node('node:name')` might fail, but `pydot.Node('"node:name"')` or `pydot.Node('node\:name')` should work. affects: All versions
gotchaThere is a separate, older project called `pydotplus` which was an 'improved version of the old pydot project'. The current `pydot` (v4.0.1) is actively maintained and the recommended library. Using `pydotplus` might lead to outdated functionality or compatibility issues with modern Python versions or other libraries.fixEnsure you are installing and importing `pydot` (`pip install pydot`) and not `pydotplus` (`pip install pydotplus`) unless you have a specific dependency on the latter.
affects: All versions where both libraries coexist
Errors
Common errors & fixes
pydot.InvocationException: GraphViz's executables not found
Pydot is a Python interface to Graphviz, which requires the Graphviz command-line tools (like 'dot', 'neato') to be installed on your system and accessible via the system's PATH environment variable.
fixInstall the Graphviz software on your operating system (e.g., `sudo apt-get install graphviz` on Linux, download the MSI installer from graphviz.org for Windows) and ensure its 'bin' directory is added to your system's PATH environment variable, then restart your terminal or IDE.
OSError: [Errno 2] "dot" not found in path
This error occurs because the 'dot' executable, part of the Graphviz command-line tools, is not found in your system's PATH environment variable, which pydot relies on to render graphs.
fixDownload and install Graphviz from its official website (graphviz.org) and add the directory containing `dot.exe` (e.g., `C:\Program Files\Graphviz\bin` on Windows or `/usr/local/bin` on Linux/macOS) to your system's PATH environment variable. Restart any running shells or IDEs.
ImportError: No module named 'pydot'
The 'pydot' Python package is not installed in the currently active Python environment, or there is a mismatch between where it's installed and the Python interpreter being used.
fixInstall the pydot package using pip: `pip install pydot`. If you are using Anaconda, you might also try `conda install pydot`. Ensure the installation is performed in the Python environment where your code is being executed.
AttributeError: module 'pydot' has no attribute 'graph_from_dot_data'
This error typically indicates a version incompatibility, where the `pydot` library version you are using does not expose a `graph_from_dot_data` attribute directly or returns a different object type than expected (e.g., a list of graphs instead of a single `Dot` object). This also occurs if `pydotplus` is expected but `pydot` is imported.
fixEnsure you have an up-to-date version of `pydot` (`pip install --upgrade pydot`). If `pydot.graph_from_dot_data` returns a list, access the first element: `graphs = pydot.graph_from_dot_data(dot_data); graph = graphs[0]`. If you intend to use `pydotplus`, ensure it is installed and imported correctly (`import pydotplus`).
AttributeError: module 'pydot' has no attribute 'InvocationException'
This error often occurs when an older version of pydot is used in combination with another library (like Keras) that expects a more recent pydot API, or it can be a symptom of the underlying 'GraphViz's executables not found' error being masked or raised differently by older versions.
fixUpgrade pydot to a more recent version (`pip install --upgrade pydot`). If the issue persists and is related to Graphviz executables, ensure Graphviz is installed and its 'bin' directory is in your system's PATH. Some users have reported resolving this by explicitly installing `pydot==2.0.0` for specific compatibility needs.
Upgrade
Version history
4.0.1latest on PyPI · released Jun 17, 2025
Audit
Dependencies
pyparsingrequiredUsed for loading DOT files; installed automatically by pip.
GraphvizrequiredEssential for rendering graphs into image formats (e.g., PNG, SVG, PDF); must be installed separately at the system level.