---
id: mermaid-py
version: "0.8.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# mermaid-py — Python Interface for the Popular mermaid-js Library, Simplified for Diagram Creation.

License: permissive · Maintenance: active · Downloads: 172.3K/mo

## What it is and what it does

mermaid-py wraps the Mermaid JavaScript library to let Python developers generate diagrams using Mermaid's declarative syntax. You write diagram definitions as strings or use Python classes to build them, and the library renders them via the mermaid.ink service (or a self-hosted instance). It integrates with Jupyter notebooks to display diagrams inline and supports flowcharts, sequence diagrams, state diagrams, entity-relationship diagrams, user journeys, pie charts, requirement diagrams, and mindmaps.

The package depends only on requests to communicate with the rendering service. It's designed for developers who want to embed diagram generation in Python scripts or notebooks without learning a separate diagramming tool or leaving their Python environment.

Use it for:

- Generate flowcharts and state diagrams programmatically in Jupyter notebooks for documentation or analysis
- Create sequence diagrams to visualize system interactions or API call flows in Python applications
- Build entity-relationship diagrams from data schemas or database designs within Python workflows
- Embed diagram generation in Python scripts to produce visual outputs for reports or dashboards
- Use mindmaps or user journey diagrams to plan and visualize project workflows interactively

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

mermaid-py provides a Python interface to the Mermaid diagram library, letting you create flowcharts, state diagrams, sequence diagrams, and other visualizations by writing Mermaid syntax in Python.

Yes, if you need to generate Mermaid diagrams from Python and work in Jupyter notebooks or can tolerate an external rendering service dependency. The low install friction, permissive license, and active maintenance make it a straightforward choice. However, note that diagram type support is incomplete (several diagram types remain unimplemented), and reliance on mermaid.ink for rendering may be a concern in offline or high-security environments.

## Install

pip install mermaid-py
uv add mermaid-py
poetry add mermaid-py

## Installing mermaid-py

Before you install: Low install friction with a single runtime dependency (requests). Maintenance status is active with a recent release.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions.

Quickstart:

pip install mermaid-py

import mermaid as md
from mermaid.graph import Graph

render = md.Mermaid("""
flowchart LR
    A-->B
    B-->C
""")
render

Requires Python 3.9 or later. Notebook rendering requires HTML support in the environment.

Verify before relying:

- Whether all diagram types listed as incomplete (Class, Gantt, Quadrant Chart, etc.) are actually unsupported or partially functional
- Performance characteristics when rendering large or complex diagrams
- Whether the mermaid.ink service dependency introduces reliability concerns for production use

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 172.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python mermaid diagram generation, flowchart creation python, visualization scripting, diagram as code python, mermaid syntax wrapper, state diagram python, sequence diagram generator, diagram-as-code, jupyter-integration, visualization

[View on SkillFed](https://skillfed.io/packages/mermaid-py) · [View on PyPI](https://pypi.org/project/mermaid-py/)