Install & Compatibility
Where this runs
tested against v? · pip install
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.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AGraph
✓ from pygraphviz import AGraph
✗ import pygraphviz.AGraph
AGraph is the primary class for graph objects and is typically imported directly or via 'import pygraphviz as pgv; pgv.AGraph()'.
This quickstart demonstrates how to create a directed graph, add nodes and edges with attributes, set global graph attributes, lay out the graph using a specified engine (e.g., 'dot'), and render it to a PNG image file.
import pygraphviz as pgv
# Create a directed graph
G = pgv.AGraph(directed=True, strict=False)
# Add nodes
G.add_node('A', shape='box', color='red')
G.add_node('B', shape='circle')
G.add_node('C', label='Node C')
# Add edges
G.add_edge('A', 'B', label='connects', penwidth=2)
G.add_edge('B', 'C', color='blue', style='dashed')
G.add_edge('C', 'A')
# Set graph attributes
G.graph_attr['label'] = 'My Sample Graph'
G.graph_attr['overlap'] = 'false'
G.graph_attr['splines'] = 'true'
# Layout the graph (using dot engine by default)
# and draw to a file
G.layout(prog='dot')
output_filename = 'sample_graph.png'
G.draw(output_filename)
print(f"Graph saved to {output_filename}")
# print(G) # Uncomment to see the DOT language representation
Debug
Known issues
breakingPyGraphviz 0.32 introduced significant API changes, being a rewrite not backward compatible with earlier versions (e.g., 0.2x). Programs written for older versions will not work without modification.fixReview the PyGraphviz 0.32+ documentation and API for the new methods and object structures. The API became similar to NetworkX.
affects: <0.32 to >=0.32
gotchaThe Graphviz C library (not the Python `graphviz` package) is a mandatory prerequisite and must be installed separately on your operating system *before* installing `pygraphviz`. Failure to do so typically results in `ImportError: libagraph.so.1: cannot open shared object file` or similar compilation errors during `pip install`.fixInstall the Graphviz C library using your system's package manager (e.g., `sudo apt-get install graphviz graphviz-dev` on Debian/Ubuntu, `brew install graphviz` on macOS) or via official installers for Windows. Ensure Graphviz binaries and libraries are on your system's PATH.
affects: All versions
gotchaInstalling PyGraphviz on Windows can be particularly challenging. It often requires specific Graphviz versions (e.g., 2.46+ for PyGraphviz 1.7+), a C/C++ compiler (like Visual C++ Build Tools), and potentially manually specifying Graphviz include and library paths during `pip install` using `--config-settings`.fixFollow the detailed Windows installation instructions in the official PyGraphviz documentation, including installing Visual C++ Build Tools and potentially using `pip install --config-settings` to point to Graphviz directories. Consider using conda or official Graphviz binaries.
affects: All versions on Windows
breakingPyGraphviz regularly drops support for older Python versions. For example, PyGraphviz 1.14 dropped Python 3.8 support. PyGraphviz 1.9 dropped Python 3.7, and 1.7 dropped 3.6.fixAlways check the `requires_python` metadata on PyPI or the official documentation for compatibility with your Python version. Upgrade Python if necessary or use an older PyGraphviz version compatible with your environment.
affects: Various, check release notes
breakingSpecific minimum Graphviz C library versions are required by newer PyGraphviz releases. For instance, PyGraphviz 1.7 requires Graphviz 2.46.0 or higher, and PyGraphviz 1.11 also requires Graphviz 2.46+.fixEnsure your system's Graphviz C library installation meets or exceeds the minimum version specified in the PyGraphviz documentation. Upgrade Graphviz if it's too old.
affects: PyGraphviz >= 1.7
Errors
Common errors & fixes
ValueError: Program dot not found in path.
PyGraphviz is a Python wrapper around the Graphviz layout engine. This error occurs because the `dot` executable (part of the Graphviz system installation) cannot be found in the system's PATH environment variable, which PyGraphviz needs to render graphs.
fixInstall the Graphviz software (not just the Python `graphviz` package) on your system and add its `bin` directory to your system's PATH environment variable. For example, on Linux, `sudo apt-get install graphviz`; on Windows, download and install from the official Graphviz website and manually add `C:\Program Files\Graphviz\bin` (or similar) to PATH.
ModuleNotFoundError: No module named 'pygraphviz'
The `pygraphviz` Python package is not installed in the currently active Python environment, or Python cannot find it. This can also happen if the Graphviz system library and its development headers were not available during `pygraphviz` installation, causing the installation to fail silently or incompletely.
fixFirst, ensure the Graphviz system library and its development headers are installed (e.g., `sudo apt-get install graphviz libgraphviz-dev pkg-config` on Debian/Ubuntu, or installing the full Graphviz package with development files on Windows). Then, install `pygraphviz` using pip: `pip install pygraphviz`.
fatal error C1083: Cannot open include file: 'graphviz/cgraph.h': No such file or directory
This error occurs during the `pygraphviz` installation process (specifically, during compilation) because the C compiler cannot find the necessary Graphviz header files, such as `cgraph.h`. This typically means the Graphviz development headers are missing or their path is not configured for the compiler.
fixEnsure that the Graphviz development packages are installed on your system. For Debian/Ubuntu, run `sudo apt-get install libgraphviz-dev`. For Fedora/RHEL, use `sudo dnf install graphviz-devel`. On Windows, ensure you install the full Graphviz package which includes development files, and you may need to specify the include and library paths during `pip install` using `--config-settings`.
AttributeError: module 'pygraphviz' has no attribute 'AGraph'
This error indicates that you are attempting to access the `AGraph` class directly from the top-level `pygraphviz` module, but it is typically expected to be imported directly or accessed after importing `pygraphviz` with an alias.
fixYou should import `AGraph` directly using `from pygraphviz import AGraph` or import `pygraphviz` as a common alias and then access `AGraph` via that alias: `import pygraphviz as pgv; G = pgv.AGraph()`.
Upgrade
Version history
1.14latest on PyPI · released Sep 29, 2024
Audit
Dependencies
Graphviz (C library)requiredPyGraphviz is a wrapper around the Graphviz C library, which must be installed separately on your system. Version 2.46 or later is required for PyGraphviz 1.7+ and recommended for 1.11+.
C/C++ CompilerrequiredRequired to compile the PyGraphviz Python wrapper. (e.g., build-essential on Linux, Xcode Command Line Tools on macOS, Visual C++ Build Tools on Windows).
python3-dev, libgraphviz-dev, pkg-configoptionalAdditional development headers and utilities often required for successful compilation on Linux distributions.