Mermaid-Python

0.1 · abandoned · verified Thu Apr 16

mermaid-python is a Python package (version 0.1) for generating diagrams using Mermaid JS. It allows you to define Mermaid diagrams as strings and render them into standalone HTML files. The project has not seen updates since its initial release over three years ago (March 2021), meaning it may not support newer Mermaid JS features or address recent issues. It is effectively abandoned.

Common errors

```
ModuleNotFoundError: No module named 'mermaid'
```
cause The 'mermaid-python' library is not installed in your current Python environment, or the environment where you installed it is not active.

fix Ensure you have installed the library correctly: `pip install mermaid-python`. If using virtual environments, activate the correct environment before running your script.
```
The generated HTML file is blank or contains only the Mermaid source code, not the diagram.
```
cause This usually indicates that the Mermaid JavaScript failed to render the diagram, most commonly due to invalid or malformed Mermaid diagram syntax in the input string.

fix Verify your Mermaid diagram string for any syntax errors using the Mermaid Live Editor (https://mermaid.live/). Also, open the generated HTML file in a browser and check its developer console for JavaScript errors related to Mermaid.
```
FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_path/my_diagram.html'
```
cause The path provided to `graph.to_file()` includes directories that do not exist.

fix Ensure that the directory where you intend to save the HTML file exists. You can create it programmatically using `os.makedirs(os.path.dirname(output_filename), exist_ok=True)` before calling `to_file()`.

Warnings

gotcha The mermaid-python project is effectively abandoned and has not been updated since its 0.1 release over three years ago (March 2021).
Fix: Be aware that it may not support recent Mermaid JS features, syntax changes, or security fixes from newer Mermaid JS versions. Consider alternative, more actively maintained libraries, or directly using Mermaid JS with a dedicated CLI or web service.
gotcha mermaid-python only renders diagrams to standalone HTML files.
Fix: For direct SVG or PNG image output, you will need to open the generated HTML file in a headless browser (e.g., using Playwright, Selenium, or Puppeteer via a subprocess) and take a screenshot, or integrate with an external Mermaid CLI tool (like `mermaid-cli` or `@mermaid-js/mermaid-cli`).
gotcha If the generated HTML file does not display your diagram, or shows a rendering error, it's almost always due to invalid Mermaid JS syntax in your input string.
Fix: Validate your Mermaid diagram string using the official Mermaid Live Editor (https://mermaid.live/) before passing it to the `Mermaid()` constructor. Check the browser's developer console when opening the HTML file for Mermaid JS specific errors.

Install

pip install mermaid-python Install stable version

Imports

Mermaid
```
from mermaid import Mermaid
```

Quickstart

This quickstart demonstrates how to define a Mermaid graph using a string and render it into a standalone HTML file. The `Mermaid` class takes the diagram definition, and `to_file()` saves it. You then open the HTML file in a browser to see the rendered diagram.

from mermaid import Mermaid

# Define your Mermaid diagram string
diagram_code = """
graph TD;
    A[Start] --> B{Process?};
    B -- Yes --> C[Do Something];
    C --> D[End];
    B -- No --> D;
"""

# Create a Mermaid object
graph = Mermaid(diagram_code)

# Render the diagram to an HTML file
output_filename = "my_mermaid_diagram.html"
graph.to_file(output_filename)

print(f"Diagram saved to {output_filename}")
# Open 'my_mermaid_diagram.html' in a web browser to view the diagram.

view raw JSON →