mermaid-py

library0.8.4pypypi✓ verified 85d ago

`mermaid-py` is a Python interface for the popular `mermaid-js` library, simplifying the creation and rendering of diagrams directly from Python code. It currently targets the latest `Mermaid.js v10+` and provides methods to output diagrams as HTML, JSON, or images. The current version is 0.8.4, with releases typically following major Mermaid.js updates or API improvements.

data serialization web-framework

pip install mermaid-py

package ↗

INSTALL

IMPORT

SIG · MERMAID-PY

mermaid-py

datapythonv0.8.4

Install

2.2s avg

Import

610ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.642s · 21.6MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.2s · import 0.578s · 22MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Mermaid

✓ from mermaid import Mermaid

✗ from mermaid_py import Mermaid

The package name is `mermaid-py`, but the top-level module to import from is `mermaid`.

This quickstart demonstrates how to define a Mermaid diagram string, create a `Mermaid` object, and retrieve its HTML and JSON representations. Image generation is commented out as it requires additional external dependencies (Playwright) to be installed and configured.

from mermaid import Mermaid import os # Define a Mermaid diagram using its text syntax graph_definition = """ graph TD; A[Start]-->B{Process Data}; B-->C[End]; """ # Create a Mermaid object diagram = Mermaid(graph_definition) # Get the HTML representation to embed or display html_output = diagram.to_html() print(f"HTML output starts with: {html_output[:50]}...") # Or get the JSON representation json_output = diagram.to_json() print(f"JSON output (first 50 chars): {json_output[:50]}...") # To generate an image, you would typically need Playwright installed and configured. # Example (requires 'pip install playwright' and 'playwright install chromium'): # if os.environ.get('MERMAID_ENABLE_IMAGE_TEST', 'false').lower() == 'true': # try: # image_data = diagram.to_image() # print(f"Generated image data (bytes length): {len(image_data)}") # except Exception as e: # print(f"Could not generate image (requires Playwright setup): {e}")

Debug

Known issues

breakingMajor rewrite in `v0.8.0` removed async dependencies and simplified the API. If you were using `mermaid-py` directly before this version, expect significant breaking changes to import paths and method signatures.

fix

Refer to the `mermaid-py` v0.8.0+ documentation for updated API usage, especially for `Mermaid` class instantiation and rendering methods. The `render()` method was removed.

affects: <0.8.0

gotcha`mermaid-py` targets `Mermaid.js v10+`. Diagrams using syntax or features from older `Mermaid.js` versions might not render as expected or may fail.

fix

Ensure your Mermaid diagram definitions adhere to `Mermaid.js v10+` syntax. Consult the official `Mermaid.js` documentation for valid syntax.

affects: all

gotchaGenerating images with `diagram.to_image()` requires additional setup, typically involving a headless browser (like Chromium) and its associated drivers via the `playwright` library.

fix

Install `playwright` (e.g., `pip install playwright`) and then run `playwright install chromium` to enable image rendering functionality.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'mermaid_py'

The Python package is `mermaid-py`, but the top-level module to import from is `mermaid`.

fix

Change your import statement from `from mermaid_py import Mermaid` to `from mermaid import Mermaid`.

AttributeError: 'Mermaid' object has no attribute 'render'

Attempting to use an old `render()` method that was removed in the `v0.8.0` rewrite.

fix

`mermaid-py` v0.8.0+ no longer has a `render()` method. Use `to_html()`, `to_json()`, or `to_image()` on the `Mermaid` object directly to get the desired output.

MermaidParseError: Syntax error in diagram (or similar rendering/parsing error)

The provided Mermaid diagram definition has invalid syntax according to `Mermaid.js` or contains unsupported features for the targeted `Mermaid.js v10+`.

fix

Review your diagram string for typos, incorrect keywords, or improper structure. Refer to the official `Mermaid.js` documentation for correct syntax for your diagram type (e.g., graph, flowchart, sequence).

Upgrade

Version history

0.8.4latest on PyPI · released Mar 9, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/mermaid-py/ ↗