mermaid-py

0.8.4 · active · verified Fri Apr 17

`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.

Common errors

```
ModuleNotFoundError: No module named 'mermaid_py'
```
cause 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'
```
cause 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)
```
cause 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).

Warnings

breaking Major 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.
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.
gotcha Generating 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.

Install

pip install mermaid-py Install mermaid-py

Imports

Mermaid
wrong:
```
from mermaid_py import Mermaid
```
correct:
```
from mermaid import Mermaid
```
The package name is `mermaid-py`, but the top-level module to import from is `mermaid`.

Quickstart

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}")

view raw JSON →