easydot 0.1.12

Tiny browser-side Graphviz DOT rendering helpers for notebooks and web views

easydot

Graphviz in the browser, from one line of Python.

pip install easydot

import easydot

easydot.display("digraph { A -> B -> C }")

---

💡 Why easydot

Graphviz usually requires a native dot binary. That's fine on a laptop, but painful in CI images, slim containers, shared clusters, and browser runtimes like JupyterLite, Pyodide, or marimo. easydot packages browser rendering so pip install easydot is enough for notebooks.

• Pip-installable. No brew, no conda, no apt-get, no Dockerfile changes.
• Browser rendering. Layout runs client-side via Graphviz WASM, so it works inside sandboxed kernels and restricted hosts.
• Tiny notebook outputs. The WASM bundle is vendored and served once over loopback instead of inlined into every cell.
• Works offline. Assets ship in the package, with a CDN fallback when loopback isn't reachable.
• Small API. easydot.display(...) renders via _repr_html_ in notebooks.

🔤 Why DOT

DOT is a small text format for graph diagrams. Many Python libraries and build tools can generate it.

• Common output format. NetworkX, pydot, pygraphviz, scikit-learn decision trees, PyTorch and TensorFlow model viz, Dask task graphs, Airflow DAGs, Terraform, Bazel, Ninja, gprof2dot, and other tools can emit DOT.
• LLM-friendly. Models can usually generate DOT for architecture diagrams, state machines, and dependency graphs.
• Plain text. Diffs cleanly, templates easily, pipes nicely.
• Graphviz features. Five layout engines (dot, neato, fdp, circo, twopi), clusters, HTML-like labels, and styling.

🚀 Usage

pydot

pip install easydot[pydot]

import easydot, pydot

graph = pydot.Dot("example", graph_type="digraph")
graph.add_edge(pydot.Edge("A", "B"))

easydot.display(graph)

NetworkX

import easydot, networkx as nx
from networkx.drawing.nx_pydot import to_pydot

G = nx.DiGraph([("A", "B"), ("B", "C"), ("A", "C")])
easydot.display(to_pydot(G))

CLI

echo 'digraph { A -> B }' | easydot     # render DOT to HTML on stdout
easydot --urls                          # print local asset server URLs

🔀 Source Modes

By default, easydot tries the local server first and falls back to a pinned CDN URL.

Mode	Local	CDN	Best for
auto	yes	yes	Most setups (default)
local	yes	no	Offline environments with no internet access
cdn	no	yes	Remote hosts where 127.0.0.1 isn't browser-reachable

easydot.display("digraph { A -> B }", source="cdn")

Environment variables

Set a notebook-wide default without editing every call:

import os
os.environ["EASYDOT_SOURCE"] = "cdn"   # auto | local | cdn

Only applies when source="auto". Explicit source= arguments still win.

For hosted marimo environments that protect generated iframe file URLs, force a self-contained iframe:

os.environ["EASYDOT_IFRAME_MODE"] = "srcdoc"   # auto | marimo | srcdoc

📓 marimo

Works out of the box. easydot detects marimo and uses its iframe display helper automatically, since marimo doesn't execute inline scripts from plain text/html outputs. All source modes work.

uv run marimo edit examples/demo.py                                   # edit the demo
uv run marimo run examples/demo.py --headless --port 2718 --no-token  # read-only preview

⏳ Large Graphs

Browser rendering is asynchronous relative to notebook cell execution: a cell can finish before the browser has loaded Graphviz WASM and produced the SVG. By default, easydot tries to run layout in a Web Worker and shows an in-progress indicator while the graph is rendering.

easydot.display(dot, worker="auto")  # default: try a worker, visibly fall back if unavailable
easydot.display(dot, worker=True)    # require a worker; no main-thread fallback
easydot.display(dot, worker=False)   # render on the output iframe's main thread

If worker rendering is unavailable and worker="auto" is used, easydot shows a warning before falling back to main-thread rendering. Large graphs may freeze that output iframe until Graphviz finishes in fallback mode.

🔌 Library Integration

For libraries that generate their own HTML, use the lower-level asset API:

from easydot import asset_urls

js_url = asset_urls()["js"]

const mod = await import(jsUrl);
const graphviz = await mod.Graphviz.load();
const svg = graphviz.layout("digraph { A -> B }", "svg", "dot");

Need server-side rendering to files? Use native Graphviz or the graphviz Python package. easydot is browser-only by design.

Runtime model

The asset server is intentionally narrow:

• Binds only to 127.0.0.1
• OS-assigned ephemeral port
• Serves only known packaged files (no directory browsing)
• Long-lived cache headers
• Shuts down automatically when the Python process exits

📜 License

Component	License
easydot Python code	BSD-3-Clause
Vendored Graphviz WASM	Apache-2.0, from @hpcc-js/wasm-graphviz. Pinned version in src/easydot/_version.py