mermaidx

Mermaid diagrams → SVG, PNG, JPG, PDF and ASCII, from plain Python.
No browser. No Node.js. No system packages. Just pip install mermaidx.

Documentation · Quick start · How it works · Python API · CLI · Changelog

import mermaidx

d = mermaidx.render("graph TD; A[Install] --> B[Import] --> C[Convert] --> D[Done]")
d.save("diagram.svg")
d.save("diagram.png", scale=2.0)

mermaidx runs the real Mermaid v11 JavaScript library inside a small embedded JS engine instead of a headless Chrome. The result is the same SVG you would get from the official mermaid-cli, produced without spawning a browser, which makes it a good fit for CI pipelines, notebooks and serverless functions.

Highlights

• Browserless. No Chromium (~170 MB), no Puppeteer, no Node.js, no compiler. Prebuilt wheels only.
• The real Mermaid. Not a reimplementation and not a subset: every diagram type Mermaid v11 supports.
• Many outputs. SVG, PNG, JPG/JPEG, BMP, TGA, PDF, raw RGBA, NumPy arrays and terminal ASCII art.
• One process. Synchronous, in-process rendering, plus render_many() for parallel batches.
• Jupyter-ready. A diagram displays itself as the last expression of a cell.
• Pluggable backends. QuickJS-ng (default), V8 (optional) or native Rust (optional).

Installation

pip install mermaidx

Extras are opt-in:

Quick start

import mermaidx

d = mermaidx.render("""
graph TD
    A[Install] --> B[Import]
    B --> C[Convert]
    C --> D[Done]
""")

d.save("diagram.svg")
d.save("diagram.png", scale=2.0)
d.save("diagram.jpg", quality=90)       # also .jpeg / .bmp / .tga
d.save("diagram.pdf", pdf_format="A4")
print(d.ascii())

The same from the command line:

mermaidx -i diagram.mermaid -o diagram.svg
mermaidx -i diagram.mermaid -o diagram.png --scale 2.0
cat diagram.mermaid | mermaidx -i - -o diagram.pdf

In Jupyter there is nothing to call. A Diagram renders itself, like a DataFrame or a matplotlib figure:

mermaidx.render("flowchart LR; A-->B-->C")   # just shows up

How it works

mermaidx has a deliberately narrow job: turn Mermaid source into an SVG that matches mermaid-cli. Everything after the SVG (PNG, JPG and friends) is novasvg's job.

flowchart TB
    SRC["Mermaid source"] --> MX
    SRC -.-> ASCII["ASCII art<br/>termaid, straight from the source"]

    subgraph MX ["mermaidx: Mermaid to SVG"]
        direction LR
        JS["JS engine<br/>QuickJS-ng, or V8 (optional)"] --> MJS["mermaid.js v11<br/>bundled, unmodified"]
        SHIM["DOM and SVG shims<br/>stand-ins for browser APIs"] -.-> MJS
    end

    MX --> SVG(["SVG<br/>same output as mermaid-cli"])
    SVG --> RAS

    subgraph NS ["novasvg: SVG to pixels"]
        direction LR
        RAS["Rasterizer<br/>paints foreignObject labels"] --> PNG["PNG"]
        RAS --> OTHER["JPG, BMP, TGA, raw RGBA"]
    end

    RAS -.-> PDF["PDF<br/>tiny stdlib-only writer in mermaidx<br/>embeds the rendered pixels"]

Every backend is a small subclass of one shared DiagramBase and only overrides the private _svg() hook. Everything downstream (png(), pdf(), raw(), numpy(), ascii(), save()) is written once and behaves identically no matter which backend produced the SVG.

Why novasvg?

Mermaid draws its labels as HTML inside <foreignObject>. Many SVG rasterizers skip that element, so the text silently disappears or the layout breaks. mermaidx originally used resvg, which cannot paint <foreignObject>, and had to force plain SVG text as a workaround. With novasvg the default HTML labels are used again, and their box sizes are computed by novasvg itself, so layout and paint cannot disagree.

In novasvg's own benchmark (60 samples, 49 of them Mermaid diagrams, compared against Chromium as ground truth), it came out the most accurate renderer while staying among the fastest:

thorvg and nanosvg are faster, but they get far more samples visibly wrong. See the benchmark page for the methodology and side-by-side renders.

Why not a browser?

The official @mermaid-js/mermaid-cli drives a real headless Chrome through Puppeteer. That works, but a browser is slow to boot and heavy to install, which shows up directly in wall-clock time for CI jobs that render many diagrams. mermaidx removes the browser and nothing else: same Mermaid library, no browser process, no page load, no DOM boot.

Every other Mermaid-to-image tool reachable from Python either drives a browser or shells out to Node.js. mermaidx is the one that renders current Mermaid with neither.

Backends

All backends share one API. List what is installed at runtime:

import mermaidx

print(mermaidx.backends())
# ['quickjs']                                    base install
# ['quickjs', 'v8']                              with mermaidx[v8engine]
# ['quickjs', 'merman', 'mermaid-rs-renderer']   with mermaidx[rust]

flowchart TB
    CALL["mermaidx.render(source, backend=...)"] --> PICK{"backend"}

    subgraph JSB ["Diagram: real mermaid.js v11 + DOM/SVG shims"]
        QJ["quickjs (default)<br/>QuickJS-ng, in-process<br/>text metrics via Python callback"]
        V8["v8<br/>V8 via mini-racer, child process<br/>text metrics via JS-side tables"]
    end

    subgraph RSB ["DiagramRust: optional mmdr package"]
        MM["merman<br/>native Rust"]
        MR["mermaid-rs-renderer<br/>native Rust"]
    end

    PICK -->|"default"| QJ
    PICK -->|"mermaidx[v8engine]"| V8
    PICK -->|"mermaidx[rust]"| MM
    PICK -->|"mermaidx[rust]"| MR

    QJ --> SVG
    V8 --> SVG
    MM --> SVG
    MR --> SVG

    SVG(["svg()<br/>the only step that differs per backend"]) --> SHARED["DiagramBase, shared by all backends<br/>novasvg: PNG, JPG, BMP, TGA, raw, numpy<br/>PDF writer<br/>save(), caching"]

The API is the same for every backend: render() always returns a Diagram, and .svg(), .png(), .pdf() and .save() work identically whichever one you pick. What is not the same is how the SVG gets made, so speed and the rendered result can differ between backends:

• quickjs and v8 run the original mermaid.js. Same library, same diagram types, same options (theme, config, css). Only the JavaScript engine differs: V8 is faster, QuickJS installs anywhere.
• merman and mermaid-rs-renderer are different implementations, written in Rust rather than JavaScript. Their layout can differ from mermaid.js, they may not support every diagram type, and they take different options (theme, node_spacing, rank_spacing, aspect_ratio instead of config and css).

Whatever the backend, the SVG then goes through the same novasvg rasterizer, so the pixels are painted the same way. Only the SVG it receives differs.

import mermaidx

source = "flowchart LR; A[Parse] --> B[Layout] --> C[Render]"

# Original mermaid.js: same output, different JS engine
mermaidx.render(source).png()                        # quickjs, the default
mermaidx.render(source, backend="quickjs").png()     # the same, spelled out
mermaidx.render(source, backend="v8").png()          # JIT, faster on big batches

# Rust reimplementations: no JS engine, output may differ
mermaidx.render(source, backend="merman").png()
mermaidx.render(source, backend="mermaid-rs-renderer").png()

To see the differences yourself, render the same diagram with every backend you have installed:

for name in mermaidx.backends():
    mermaidx.render(source, backend=name).save(f"diagram-{name}.png")

Options depend on the family:

# mermaid.js backends: config and css
mermaidx.render(source, theme="dark", config={"flowchart": {"curve": "basis"}})

# Rust backends: spacing and aspect ratio
mermaidx.render(source, backend="merman", theme="dark", node_spacing=60, rank_spacing=80)

Python API

render() only stores the source. Every Diagram method is lazy and cached: nothing is computed until you call it, and repeating a call returns the memoized result.

d = mermaidx.render("flowchart LR; A-->B-->C")
d.svg() is d.svg()   # True, the second call is a cache hit

d.save("out.png")                      # format from the extension
d.save("out.whatever", format="png")   # or forced explicitly
d.save("out.pdf", pdf_format="A4", pdf_margin="1cm")

Themes, config and CSS

mermaidx.render(source, theme="dark")   # "default" | "forest" | "dark" | "neutral"
mermaidx.render(source, config={"flowchart": {"curve": "basis"}})
mermaidx.render(source, css=".node rect { rx: 8; ry: 8; }")

Parallel batches. Rendering is pure CPU work, so real concurrency means processes rather than async. Each worker starts its own engine once and reuses it:

diagrams = mermaidx.render_many(sources, workers=4, theme="dark")
for d, name in zip(diagrams, output_names):
    d.save(name)

ASCII output works out of the box (termaid is a core dependency):

print(mermaidx.render_ascii("graph LR; A-->B-->C"))

┌───┐    ┌───┐    ┌───┐
│ A ├───►│ B ├───►│ C │
└───┘    └───┘    └───┘

Rasterize any SVG without going through render():

from mermaidx import svg_to_png, svg_to_raw

svg = open("diagram.svg").read()
png = svg_to_png(svg, width=1200, background="#ffffff")
raw, w, h = svg_to_raw(svg)

Full reference: Python API docs.

CLI

mermaidx -i diagram.mermaid                        # SVG to stdout
mermaidx -i diagram.mermaid -o diagram.png         # format from the extension
mermaidx -i diagram.mermaid -o diagram.png -w 1200 # or --scale 2.0
mermaidx -i diagram.mermaid -o diagram.svg --theme dark
mermaidx -i diagram.mermaid -o diagram.pdf --pdf-format A4 --landscape --margin 1cm
mermaidx -i diagram.mermaid -o diagram.svg --config config.json --css style.css
mermaidx -i diagram.mermaid -o diagram.svg --backend merman   # needs mermaidx[rust]

mermaidx --list-backends
mermaidx --info          # bundled Mermaid version
mermaidx --version

Use -q to silence the "saved to…" message and --quality N for JPEG quality. More in the CLI docs.

Supported diagrams

Everything Mermaid v11 itself supports, because the real library is bundled: flowcharts, sequence, class, state, ER, Gantt, pie, git graphs, mindmaps, timelines, and more.

Requirements

• Python 3.9+
• quickjs-ng, novasvg, termaid (installed automatically)
• mini-racer (optional, for backend="v8")

Documentation

Testing

pip install -e ".[test]"
pytest tests/ -v

History

Acknowledgments

• Mermaid: the diagramming library this project renders. mermaidx just runs the real thing somewhere a browser can't go.
• novasvg: SVG rasterization, image encoding and text measurement.
• mmdr: a native-Rust Mermaid renderer by the same author, usable as an extra backend.
• termaid: powers ASCII/Unicode terminal output.

Contributing

1. Fork and create a feature branch.
2. Add tests for new functionality.
3. Run pytest tests/. Everything must pass.
4. Open a pull request.

License

MIT. See LICENSE.