{"record":{"id":"60b938adb0f03c35","repo":"pola-rs/polars","slug":"the-graphviz-dot-binary-should-be-on-your-path","errorCode":null,"errorMessage":"the graphviz `dot` binary should be on your PATH.(If not installed you can download here: https://graphviz.org/download/)","messagePattern":"the graphviz `dot` binary should be on your PATH\\.\\(If not installed you can download here: https://graphviz\\.org/download/\\)","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/various.py","lineNumber":655,"sourceCode":"    output_type = (\n        \"svg\"\n        if (output_path is not None and str(output_path).endswith(\".svg\"))\n        or _in_notebook()\n        or _in_marimo_notebook()\n        or \"POLARS_DOT_SVG_VIEWER\" in os.environ\n        else \"png\"\n    )\n\n    try:\n        graph = subprocess.check_output(\n            [\"dot\", \"-Nshape=box\", \"-T\" + output_type], input=f\"{dot}\".encode()\n        )\n    except (ImportError, FileNotFoundError):\n        msg = (\n            \"the graphviz `dot` binary should be on your PATH.\"\n            \"(If not installed you can download here: https://graphviz.org/download/)\"\n        )\n        raise ImportError(msg) from None\n\n    if output_path:\n        Path(output_path).write_bytes(graph)\n\n    if not show:\n        return None\n\n    if _in_notebook():\n        from IPython.display import SVG, display\n\n        return display(SVG(graph))\n    elif _in_marimo_notebook():\n        import marimo as mo\n\n        return mo.Html(f\"{graph.decode()}\")\n    else:\n        if (cmd := os.environ.get(\"POLARS_DOT_SVG_VIEWER\", None)) is not None:\n            import tempfile","sourceCodeStart":637,"sourceCodeEnd":673,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/various.py#L637-L673","documentation":"ImportError from display_dot_graph (py-polars/src/polars/_utils/various.py:646-655), reached via LazyFrame.show_graph() and Expr.meta.show_graph(). Rendering the query-plan graph shells out to the graphviz `dot` executable (subprocess ['dot', '-Nshape=box', ...]); if the binary is not on PATH the FileNotFoundError is converted into this ImportError telling you to install graphviz. The pip package `graphviz` alone is not enough — the C system package provides the binary.","triggerScenarios":"lf.show_graph() or expr.meta.show_graph() on a machine without the graphviz system package; slim Docker images (python:*-slim, distroless) where graphviz was never installed; fresh CI runners.","commonSituations":"Debugging lazy query plans in notebooks after a container rebuild; `pip install graphviz` performed instead of the system install; PATH modifications in venv/conda that shadow or drop the binary.","solutions":["Install the system package: apt-get install graphviz / brew install graphviz / apk add graphviz","If you only need the plan text, call lf.show_graph(raw_output=True) to get the DOT string without invoking dot, or use lf.explain()","Persist the DOT and render elsewhere: write the raw_output string to a .dot file and render on a machine with graphviz","In Dockerfiles add the graphviz package to the image"],"exampleFix":"# before\nlf.show_graph()  # ImportError: dot not on PATH\n\n# after (no binary needed)\ndot_source = lf.show_graph(raw_output=True)\nPath('plan.dot').write_text(dot_source)\n\n# and in the image: RUN apt-get update && apt-get install -y graphviz","handlingStrategy":"validation","validationCode":"import shutil\n\ndef dot_available() -> bool:\n    return shutil.which('dot') is not None","typeGuard":null,"tryCatchPattern":"try:\n    lf.show_graph(figsize=(16, 12))\nexcept ImportError as e:\n    if 'dot' in str(e):\n        print(lf.explain())  # textual plan fallback\n    else:\n        raise","preventionTips":["Install the graphviz system package in images/notebook environments upfront","Prefer lf.explain() for text plans; use show_graph(raw_output=True) when dot is unavailable","pip install graphviz does not provide the binary — always install the OS package"],"tags":["polars","graphviz","show-graph","environment","importerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}