Render Mermaid diagrams from Python, with no browser

mermaidx runs the real mermaid.js inside a small embedded engine. One pip install gives you SVG, PNG, JPEG, PDF and ASCII output, with no Node.js, no Chrome and nothing to compile.

pip install mermaidx

Get started See the benchmarks

import mermaidx

diagram = mermaidx.render("""
sequenceDiagram
    autonumber
    loop Every Second
        App->>Engine: Check Status
    end
    alt Engine is Free
        App->>Engine: Send Job
        Engine-->>App: Job Accepted
    else Engine is Busy
        Engine-->>App: Queue Full Error
    end
    
""")
diagram.save("diagram.png")

import mermaidx

diagram = mermaidx.render("""
architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service disk2(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db
""")
diagram.save("diagram.png")

import mermaidx

diagram = mermaidx.render("""
quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]
""")
diagram.save("diagram.png")

import mermaidx

diagram = mermaidx.render("""
sankey-beta

Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
Solar,Electricity grid,59.9
Solid,Electricity grid,280.322
""")
diagram.save("diagram.png")

import mermaidx

diagram = mermaidx.render("""
venn-beta
  title "Team overlap"
  set A["Frontend"]
  set B["Backend"]
  set C["DevOps"]
  union A,B["Fullstack"]
  union B,C["Platform"]
  union A,B,C["Everyone"]
""")
diagram.save("diagram.png")

import mermaidx

diagram = mermaidx.render("""
gitGraph
    commit id: "init"
    commit id: "add readme"
    branch develop
    checkout develop
    commit id: "feature A"
    commit id: "feature B" tag: "v0.1"
    checkout main
    merge develop id: "merge dev"
    branch hotfix
    checkout hotfix
    commit id: "fix crash" type: REVERSE
    checkout main
    merge hotfix id: "merge hotfix" tag: "v1.0"
    commit id: "release" type: HIGHLIGHT
""")
diagram.save("diagram.png")

Left: the Python you write. Right: the diagram.png it produces, with no browser involved.

What you do not need to install

The official mermaid-cli starts a headless Chrome for every diagram, which means installing Node.js and around 170 MB of Chromium. In a CI pipeline or a serverless function, that is most of the time spent. mermaidx renders the same Mermaid library without a browser, so a diagram is one Python call.

Four backends, one API

quickjs is the default and has no dependencies. v8 is faster for large batches. merman and mermaid-rs-renderer are native Rust renderers. Switching is one argument: mermaidx.render(source, backend="v8"). The backends page says when to choose each.

Checked against mermaid-cli

The SVG output is compared with mmdc on 43 reference diagrams using a strict structural comparison. The benchmark gallery shows the same diagrams rendered by all five renderers, side by side, with the time each one took.