---
id: sphinxcontrib-mermaid
version: "2.1.0"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# sphinxcontrib-mermaid — Mermaid diagrams in your Sphinx-powered docs

License: permissive · Maintenance: active · Downloads: 6.4M/mo

## What it is and what it does

sphinxcontrib-mermaid is a Sphinx extension that lets you write Mermaid diagram syntax directly in your reStructuredText or Markdown documentation and have them render as interactive diagrams in the final HTML output. It integrates with Sphinx's build pipeline and depends on Jinja2, PyYAML, and Sphinx itself to process and embed the diagrams.

The extension is useful when you want to include flowcharts, sequence diagrams, Gantt charts, and other visual representations in technical documentation without manually creating image files. You write the diagram definition in plain text using Mermaid's syntax, and the extension handles conversion to rendered graphics during the Sphinx build.

Use it for:

- Add flowcharts and process diagrams to API documentation or architecture guides.
- Include sequence diagrams in technical specifications or protocol documentation.
- Embed Gantt charts in project planning or timeline documentation.
- Create state machine diagrams for explaining system behavior or workflows.
- Build interactive diagrams that render consistently across all documentation builds.

## Worth the install?

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

Embeds Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, and more) directly into Sphinx-generated documentation.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, uses a permissive license, and solves a clear documentation need. It is well-suited for any Sphinx-based project that benefits from embedded diagrams. Install it if you are using Sphinx and want to include Mermaid diagrams without managing separate image files.

## Install

pip install sphinxcontrib-mermaid
uv add sphinxcontrib-mermaid
poetry add sphinxcontrib-mermaid

## Installing sphinxcontrib-mermaid

Before you install: Low install friction with three straightforward runtime dependencies. Actively maintained with a recent release 27 days ago and ongoing commits; the repository has 409 stars and is not archived.

License in practice: BSD-2-Clause is permissive, allowing commercial and private use with minimal restrictions beyond retaining the license notice.

Quickstart:

pip install sphinxcontrib-mermaid

# In conf.py:
extensions = ['sphinxcontrib.mermaid']

# In your .rst file:
.. mermaid::

   graph LR
      A --> B

Requires Python 3.10 or later; Sphinx must be installed and configured in your documentation project.

Verify before relying:

- Whether Mermaid JavaScript library is automatically bundled or requires separate installation in the build environment.
- Support for all Mermaid diagram types (e.g., state diagrams, class diagrams, entity-relationship diagrams) beyond those mentioned in the description.

## Package facts

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx mermaid diagrams, embed flowcharts in sphinx docs, sequence diagrams sphinx, gantt charts documentation, sphinx diagram extension, mermaid sphinx plugin, documentation visualization, sphinx-extension, diagram-rendering, documentation-tooling

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