Mermaid CLI (Python)
A command-line interface and Python library for mermaid, which allows you to generate diagrams and flowcharts from text.
This code has been ported to Python from the following library: https://github.com/mermaid-js/mermaid-cli
Features
- Render Mermaid diagrams to SVG, PNG, or PDF formats
- Process Markdown files with embedded Mermaid diagrams
- Use as a command-line tool or Python library
- Customize output with themes, colors, and CSS
- Support for icon packs
Installation
pip install mermaid-cli
After installation, you need to install the Playwright browsers:
playwright install chromium
Usage
Command Line
# Simple diagram rendering
mmdc -i input.mmd -o output.svg
# Markdown file with mermaid diagrams
mmdc -i input.md -o output.md
# Customize output
mmdc -i input.mmd -o output.png -t dark -b transparent -w 1024 -H 768
Playwright Config (Custom Executable)
If you cannot install the bundled Playwright Chromium, you can point to a custom
binary and pass additional launch args using --playwright-config-file:
{
"headless": true,
"executable_path": "/path/to/chromium",
"args": ["--no-sandbox", "--disable-gpu"]
}
Python usage with a custom executable:
await render_mermaid(
definition,
output_format="svg",
playwright_config={
"headless": True,
"executable_path": "/path/to/chromium",
"args": ["--no-sandbox", "--disable-gpu"],
},
)
Python Library
import asyncio
from mermaid_cli import render_mermaid, render_mermaid_file
# Render a diagram directly
async def render_diagram():
definition = """
graph TD
A[Start] --> B{Is it?}
B -->|Yes| C[OK]
C --> D[Rethink]
D --> B
B ---->|No| E[End]
"""
title, desc, svg_data = await render_mermaid(
definition,
output_format="svg",
background_color="white",
mermaid_config={"theme": "forest"}
)
with open("output.svg", "wb") as f:
f.write(svg_data)
# Render from a file
async def render_file():
await render_mermaid_file(
input_file="input.mmd",
output_file="output.svg",
output_format="svg",
mermaid_config={"theme": "dark"}
)
# Run the async functions
asyncio.run(render_diagram())
asyncio.run(render_file())
# Or use the synchronous wrapper
from mermaid_cli import render_mermaid_file_sync
render_mermaid_file_sync(
input_file="input.mmd",
output_file="output.png",
output_format="png"
)
Command Line Options
| Option | Description |
|---|---|
-t, --theme [theme] |
Theme of the chart (default, forest, dark, neutral) |
-w, --width [width] |
Width of the page |
-H, --height [height] |
Height of the page |
-i, --input <input> |
Input mermaid file or markdown with mermaid code blocks |
-o, --output [output] |
Output file (svg, png, pdf, or md) |
-e, --output-format [format] |
Output format (svg, png, pdf) |
-b, --background-color [color] |
Background color (e.g., transparent, white, #F0F0F0) |
-c, --config-file [file] |
JSON configuration file for mermaid |
-C, --css-file [file] |
CSS file for styling the output |
-I, --svg-id [id] |
ID attribute for the SVG element |
-s, --scale [scale] |
Browser scale factor |
-f, --pdf-fit |
Scale PDF to fit chart |
-q, --quiet |
Suppress log output |
-p, --playwright-config-file [file] |
JSON configuration file for Playwright launch options |
--icon-packs <icons...> |
Icon packs to use (e.g., @iconify-json/logos) |
API Reference
render_mermaid
async def render_mermaid(
definition: str,
output_format: str = "svg",
viewport: Dict[str, int] = None,
background_color: str = "white",
mermaid_config: Dict[str, Any] = None,
css: str = None,
pdf_fit: bool = False,
svg_id: str = None,
icon_packs: List[str] = None,
playwright_config: Dict[str, Any] = None,
) -> Tuple[Optional[str], Optional[str], bytes]
Renders a Mermaid diagram definition to the specified format.
Parameters:
definition: Mermaid diagram definition stringoutput_format: Output format (svg, png, pdf)viewport: Viewport dimensions (width, height, deviceScaleFactor)background_color: Background colormermaid_config: Mermaid configuration dictionarycss: Custom CSS stringpdf_fit: Scale PDF to fit chartsvg_id: ID attribute for the SVG elementicon_packs: List of icon packages to useplaywright_config: Playwright launch options dictionary (e.g.,headless,executable_path,args)
Returns: A tuple of (title, description, data) where data is the binary content of the rendered diagram.
render_mermaid_file
async def render_mermaid_file(
input_file: Optional[str],
output_file: str,
output_format: Optional[str] = None,
playwright_config: Dict[str, Any] = None,
quiet: bool = False,
**kwargs
) -> None
Renders a Mermaid diagram from a file or processes a Markdown file with embedded Mermaid diagrams.
Parameters:
input_file: Path to input file or None for stdinoutput_file: Path to output fileoutput_format: Output format (svg, png, pdf)playwright_config: Playwright launch options dictionaryquiet: Suppress log output**kwargs: Additional options for render_mermaid
render_mermaid_file_sync
def render_mermaid_file_sync(
input_file: Optional[str],
output_file: str,
output_format: Optional[str] = None,
**kwargs
) -> None
Synchronous wrapper for render_mermaid_file.
Examples
Basic Flowchart
graph TD
A[Start] --> B{Is it?}
B -->|Yes| C[OK]
C --> D[Rethink]
D --> B
B ---->|No| E[End]
Sequence Diagram
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
Class Diagram
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
License
MIT
Metadata
Release files for mermaid-cli 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mermaid_cli-0.1.3.tar.gz | 25.2 kB | Without provenance | Details for mermaid_cli-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mermaid_cli-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for mermaid_cli-0.1.3-py3-none-any.whl |
Total release size: 41.2 kB
Release files / mermaid_cli-0.1.3.tar.gz
| Download URL | mermaid_cli-0.1.3.tar.gz |
|---|---|
| Size | 25.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a9116e898c4fefaced3a1256ac9a9741e973f30d9c82d49b9674832413e92b79
|
|
BLAKE2b-256 checksum How to use checksums |
f1448d96d296f5cdcdf882b8dd1ee5d37723052dfafb7322c6bc4ac30ea228f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / mermaid_cli-0.1.3-py3-none-any.whl
| Download URL | mermaid_cli-0.1.3-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49c437a5611f83279111a44cf3fa646e9d573281ef4c4425f4d8e089821684bf
|
|
BLAKE2b-256 checksum How to use checksums |
d02f08d76ceaa38827863c702dd73a0f50ee1532aa6eae393e80ca82ee2c6396
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for mermaid-cli 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.