Render Mermaid diagrams in your terminal or Python app.
- 7 diagram types: flowcharts, sequence, class, ER, state, block, and git graphs
- Zero dependencies: pure Python, nothing to install beyond the package itself
- Rich and Textual integration: colored output and TUI widgets with optional extras
- 6 color themes: default, terra, neon, mono, amber, phosphor
- ASCII fallback: works on any terminal, even the most basic ones
- Pipe-friendly CLI:
cat diagram.mmd | termaidjust works
Mermaid is great for documentation, but rendering it usually means spinning up a browser or calling an external service. termaid lets you render diagrams over SSH, in CI logs, inside TUI apps, or anywhere you have a Python environment. It was built because the existing tools in this space, like mermaid-ascii (Go) and beautiful-mermaid (TypeScript), don't offer a native Python library you can import and call directly.
pip install termaidOr try it without installing:
uvx termaid diagram.mmdtermaid diagram.mmd
echo "graph LR; A-->B-->C" | termaid
termaid diagram.mmd --theme neon
termaid diagram.mmd --asciifrom termaid import render
print(render("graph LR\n A --> B --> C"))# Colored output (requires: pip install termaid[rich])
from termaid import render_rich
from rich import print as rprint
rprint(render_rich("graph LR\n A --> B", theme="terra"))# Textual TUI widget (requires: pip install termaid[textual])
from termaid import MermaidWidget
widget = MermaidWidget("graph LR\n A --> B")All directions supported: LR, RL, TD/TB, BT.
graph TD
A[Start] --> B{Is valid?}
B -->|Yes| C(Process)
C --> D([Done])
B -->|No| E[Error]
┌─────────────┐
│ │
│ Start │
│ │
└──────┬──────┘
│
│
▼
┌──────◇──────┐
│ │
│ Is valid? │
│ │
└──────◇──────┘
│
│
╰──────────────────╮
Yes│ │No
▼ ▼
╭─────────────╮ ┌─────────────┐
│ │ │ │
│ Process │ │ Error │
│ │ │ │
╰──────┬──────╯ └─────────────┘
│
│
▼
╭─────────────╮
( )
( Done )
( )
╰─────────────╯
Node shapes: rectangle [text], rounded (text), diamond {text}, stadium ([text]), subroutine [[text]], circle ((text)), double circle (((text))), hexagon {{text}}, cylinder [(text)], asymmetric >text], parallelogram [/text/], trapezoid [/text\], and @{shape} syntax
Edge styles: solid -->, dotted -.->, thick ==>, bidirectional <-->, circle endpoint --o, cross endpoint --x, labeled -->|text|, variable length --->, ---->
Styling: classDef, style, linkStyle directives, :::className suffix
Subgraphs: nesting, cross-boundary edges, per-subgraph direction override
Other: %% comments, ; line separators, Markdown labels "`**bold** *italic*`", & operator (A & B --> C)
sequenceDiagram
Alice->>Bob: Hello Bob
Bob-->>Alice: Hi Alice
Alice->>Bob: How are you?
Bob-->>Alice: Great!
┌──────────┐ ┌──────────┐
│ Alice │ │ Bob │
└──────────┘ └──────────┘
┆ Hello Bob ┆
──────────────────►
┆ Hi Alice ┆
◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┆ How are you? ┆
──────────────────►
┆ Great! ┆
◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
┆ ┆
Message types: solid arrow ->>, dashed arrow -->>, solid line ->, dashed line -->
Participants: participant, actor, aliases
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+fetch()
}
Animal <|-- Dog
┌──────────────┐
│ Animal │
├──────────────┤
│ +String name │
│ +int age │
├──────────────┤
│ +makeSound() │
└──────────────┘
△
│
│
│
┌───────────────┐
│ Dog │
├───────────────┤
│ +String breed │
├───────────────┤
│ +fetch() │
└───────────────┘
Relationships: inheritance <|--, composition *--, aggregation o--, association --, dependency ..>, realization ..|>
Members: attributes and methods with visibility (+ public, - private, # protected, ~ package)
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
┌──────────────┐
│ CUSTOMER │
└──────────────┘
│1
│ places
│
│0..*
┌──────────────┐
│ ORDER │
└──────────────┘
│1
│ contains
│
│1..*
┌──────────────┐
│ LINE-ITEM │
└──────────────┘
Cardinality: || (exactly one), o| (zero or one), }| (one or more), o{ (zero or more)
Line styles: solid --, dashed ..
Attributes: type, name, keys (PK, FK, UK), comments
stateDiagram-v2
[*] --> Idle
Idle --> Processing : start
Processing --> Done : complete
Done --> [*]
╭───────◯──────╮
│ │
│ ● │
│ │
╰───────◯──────╯
│
│
▼
╭──────────────╮
│ │
│ Idle │
│ │
╰───────┬──────╯
│
start│
▼
╭──────────────╮
│ │
│ Processing │
│ │
╰───────┬──────╯
│
complete│
▼
╭──────────────╮
│ │
│ Done │
│ │
╰───────┬──────╯
│
│
▼
╭───────◯──────╮
│ │
│ ◉ │
│ │
╰───────◯──────╯
Features: [*] start/end states, transition labels, state "name" as alias, composite states (state Parent { }), stereotypes (<<choice>>, <<fork>>, <<join>>)
block-beta
columns 3
A["Frontend"] B["API"] C["Database"]
┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ │ │ │ │
│ Frontend │ │ API │ │ Database │
│ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
Features: columns N, column spanning (blockname:N), links between blocks, nested blocks
gitGraph
commit id: "init"
commit id: "feat"
branch develop
commit id: "dev-1"
commit id: "dev-2"
checkout main
commit id: "fix"
merge develop id: "merge"
main ───●─────●──────┼──────────────●──────●─
init feat │ fix merge
│ │
develop ●───────●─────────────┼
dev-1 dev-2
Directions: LR (default), TB, BT
Commands: commit (with id:, type:, tag:), branch (with order:), checkout/switch, merge, cherry-pick
Commit types: NORMAL (●), REVERSE (✖), HIGHLIGHT (■)
Config: %%{init: {"gitGraph": {"mainBranchName": "master"}}}%%
| Flag | Description |
|---|---|
--tui |
Interactive TUI viewer (requires pip install termaid[tui]) |
--ascii |
ASCII-only output (no Unicode box-drawing) |
--theme NAME |
Color theme: default, terra, neon, mono, amber, phosphor (requires pip install termaid[rich]) |
--padding-x N |
Horizontal padding inside boxes (default: 4) |
--padding-y N |
Vertical padding inside boxes (default: 2) |
--sharp-edges |
Sharp corners on edge turns instead of rounded |
Render a Mermaid diagram as a plain text string. Auto-detects diagram type.
Render as a Rich Text object with colors. Requires pip install termaid[rich].
A Textual widget with a reactive source attribute. Requires pip install termaid[textual]. Updates live when you change the source property.
from termaid import MermaidWidget
class MyApp(App):
def compose(self):
yield MermaidWidget("graph LR\n A --> B")Six built-in themes for --theme / render_rich():
| Theme | Colors | Description |
|---|---|---|
default |
   |
Cyan nodes, yellow arrows, white labels |
terra |
   |
Warm earth tones (browns, oranges) |
neon |
  |
Magenta nodes, green arrows, cyan edges |
mono |
  |
White/gray monochrome |
amber |
   |
Amber/gold CRT-style |
phosphor |
   |
Green phosphor terminal-style |
pip install termaid[rich] # Colored terminal output
pip install termaid[textual] # Textual TUI widget- Layout engine is approximate. Node positioning uses a grid-based barycenter heuristic. Graphs with many cross-layer edges may still produce crossings.
- Manhattan-only edge routing. Edges use A* pathfinding on a grid. Very dense graphs may have overlapping edges.
Inspired by mermaid-ascii by Alexander Grooff and beautiful-mermaid by Lukilabs.
MIT