langchain-ai/langchain · error · ImportError

Install pygraphviz to draw graphs: `pip install pygraphviz`.

Error message

Install pygraphviz to draw graphs: `pip install pygraphviz`.

What it means

draw_png() uses pygraphviz to lay out and rasterize the graph. If the pygraphviz import failed at module load (_HAS_PYGRAPHVIZ False), it raises this ImportError with the install hint. pygraphviz requires both the Python package and the system graphviz headers, so installation can fail at the C level.

Source

Thrown at libs/core/langchain_core/runnables/graph_png.py:137

    def draw(self, graph: Graph, output_path: str | None = None) -> bytes | None:
        """Draw the given state graph into a PNG file.

        Requires `graphviz` and `pygraphviz` to be installed.

        Args:
            graph: The graph to draw
            output_path: The path to save the PNG. If `None`, PNG bytes are returned.

        Raises:
            ImportError: If `pygraphviz` is not installed.

        Returns:
            The PNG bytes if `output_path` is None, else None.
        """
        if not _HAS_PYGRAPHVIZ:
            msg = "Install pygraphviz to draw graphs: `pip install pygraphviz`."
            raise ImportError(msg)

        # Create a directed graph
        viz = pgv.AGraph(directed=True, nodesep=0.9, ranksep=1.0)

        # Add nodes, conditional edges, and edges to the graph
        self.add_nodes(viz, graph)
        self.add_edges(viz, graph)
        self.add_subgraph(viz, [node.split(":") for node in graph.nodes])

        # Update entrypoint and END styles
        self.update_styles(viz, graph)

        # Save the graph as PNG
        try:
            return cast("bytes | None", viz.draw(output_path, format="png", prog="dot"))
        finally:
            viz.close()

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Install system Graphviz first (apt install graphviz-dev / brew install graphviz), then pip install pygraphviz
2. Verify: python -c "import pygraphviz"
3. Use graph.draw_mermaid_png() (requests-based) as an alternative PNG renderer

Example fix

# before
graph.draw_png() # ImportError
# after (debian/ubuntu)
apt-get install -y graphviz graphviz-dev && pip install pygraphviz
graph.draw_png()

try:
    import pygraphviz  # noqa: F401
    can_draw = True
except ImportError:
    can_draw = False
if not can_draw:
    png = graph.draw_mermaid_png()  # alternative renderer

try:
    png = graph.draw_png()
except ImportError as e:
    if "pygraphviz" in str(e):
        png = graph.draw_mermaid_png()

When it happens

Trigger: Calling graph.draw_png() (or graph_png.draw_png) without pygraphviz installed, or where pygraphviz failed to build/import (missing system graphviz).

Common situations: Slim Docker images lacking graphviz system libs; Alpine/musl builds; macOS without `brew install graphviz`; Windows without Graphviz in PATH.

Related errors

• Install Pyppeteer to use the Pyppeteer method: `pip install
• Install the `requests` module to use the Mermaid.INK API: `p
• Install grandalf to draw graphs: `pip install grandalf`.
• Invalid draw method: {draw_method}. Supported draw methods a
• jinja2 not installed, which is needed to use the jinja2_form

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/5652af6594cbb381. Report an issue: GitHub.