Mermaid vs PlantUML vs Graphviz

TL;DR: Use Mermaid for diagrams that live beside your code, because GitHub renders it in Markdown and nothing needs installing. Use PlantUML for formal UML, because it covers all nine UML diagram types in depth. Use Graphviz when something generates the graph for you, or when it is too big for the other two to lay out sensibly.

The thing most comparisons miss

These three are not three competing products. PlantUML uses Graphviz to lay out several of its diagram types. Its own FAQ says PlantUML "is using Graphviz to generate some diagrams", and lists the Graphviz versions it has been tested against. Class and component diagrams go through Graphviz; sequence diagrams and some others are laid out by PlantUML itself.

So a fair way to picture it: Graphviz is a layout engine, PlantUML is a modelling language that leans on that engine, and Mermaid is a documentation tool that brought its own layout to the browser. Choosing between them is mostly a question of which layer you want to work at.

The same diagram in all three

Here is one small decision, written three ways. Mermaid:

flowchart LR
    A[Order placed] --> B{In stock?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Back-order]

PlantUML, as an activity diagram:

@startuml
start
:Order placed;
if (In stock?) then (yes)
  :Ship it;
else (no)
  :Back-order;
endif
stop
@enduml

Graphviz, in the DOT language:

digraph orders {
  rankdir=LR;
  A [label="Order placed", shape=box];
  B [label="In stock?", shape=diamond];
  A -> B;
  B -> "Ship it" [label="yes"];
  B -> "Back-order" [label="no"];
}

The differences are already visible. Mermaid encodes the shape in the brackets, so {In stock?} is a diamond. PlantUML uses keywords that read like pseudocode, and knows what an activity diagram is supposed to look like. Graphviz makes you state the shape yourself, because it has no idea what a flowchart is: it draws graphs, and a flowchart is just one.

At a glance

Mermaid: diagrams that live with your code

Mermaid is a JavaScript library, MIT licensed, that turns text into SVG in the browser. Its distinguishing feature is not its syntax but its reach: GitHub renders Mermaid natively inside Markdown. GitHub's documentation lists four diagram syntaxes it will draw in a fenced code block, and Mermaid is one of them, alongside GeoJSON, TopoJSON and ASCII STL. PlantUML and DOT are not on that list.

That single fact decides a lot of cases. If the diagram belongs in a README, a pull request description or an issue, Mermaid is the only one of the three that a reader sees as a picture rather than as a wall of source or a committed PNG that is already out of date.

Mermaid covers flowcharts, sequence, class, state and ER diagrams, mind maps, Gantt charts, timelines and more, each documented in our diagram type guides.

Where it is weaker: layout control. You choose a direction and can nudge things, but you do not get Graphviz's set of engines, and large flowcharts become tangled. Its UML support is also partial: it draws class and state diagrams, but not the full nine, and not to the depth PlantUML offers. If you are doing formal modelling, that gap matters.

PlantUML: when you need real UML

PlantUML is the most complete of the three for software modelling. It covers all nine UML diagram types — sequence, use case, class, object, activity, component, deployment, state and timing — plus roughly seventeen other formats, including JSON and YAML data, wireframes, Gantt charts, mind maps, network diagrams, ArchiMate and Entity Relationship diagrams in Chen's notation.

It exports PNG, SVG, LaTeX and EPS, which matters if your diagrams end up in a typeset document rather than a web page.

The cost is setup. PlantUML is a Java program. You need a JVM, and for several diagram types you also need Graphviz installed. There is an official server that renders from a URL, and a small built-in web server for running it privately, which the FAQ recommends for sensitive diagrams.

Licensing needs a moment's thought. PlantUML is GPL by default, with LGPL, Apache, EPL and MIT versions also offered. The FAQ is explicit that images you generate are not covered by its licence, so your diagrams are yours. If you are embedding PlantUML in a closed product, the LGPL build is the one to read carefully.

Graphviz: the layout engine underneath

Graphviz started at AT&T Labs Research and is the oldest of the three. You describe nodes and edges in the DOT language and it decides where everything goes. Version 16.0.0 arrived in August 2026, and the project moved from the Common Public License to the Eclipse Public License 2.0 in March 2026.

Its real advantage is ten layout engines, each for a different shape of problem:

• dot — hierarchical layouts of directed graphs; the usual choice.
• neato and fdp — spring models for undirected graphs.
• sfdp — the scalable version, built for graphs too big for the others.
• circo and twopi — circular and radial layouts.
• osage and patchwork — clustered graphs and treemaps.

This is why Graphviz is what tools reach for when a graph is generated: dependency trees, call graphs, state machines dumped from code. Nobody writes a 2,000-node DOT file by hand, but plenty of programs emit one.

Where it is weaker: it knows nothing about diagram conventions. There is no "sequence diagram" in DOT, no lifelines, no UML stereotypes. Anything semantic, you build yourself out of nodes, edges and shapes.

How to choose

The decision, as a diagram:

• Diagrams in a README, docs site or pull request → Mermaid. Nothing to install, and GitHub draws it.
• Formal UML, or diagrams headed for a LaTeX document → PlantUML. Accept the Java dependency.
• A graph your code generates, or one with hundreds of nodes → Graphviz, with dot or sfdp.
• Not sure yet → Mermaid, because it is the cheapest to abandon. Nothing is installed and the syntax is small.

A note on switching later

There is no reliable converter between these three, and there cannot really be one: they describe different things at different levels. A basic flowchart moves across by hand in a few minutes. A PlantUML class diagram with stereotypes and notes has no direct Mermaid equivalent, and a hand-tuned DOT graph loses its layout work in either direction.

The practical advice is to pick per diagram, not per company. A repository can hold Mermaid in its README and a generated DOT file in its build output without any conflict. What costs time is deciding that everything must be one tool, then discovering the tool cannot draw the one diagram that matters most.

If Mermaid is where you land and writing the syntax is the part you would rather skip, that is the gap TryMermaid fills: drag shapes on a canvas and it writes plain Mermaid code, which still opens anywhere Mermaid does. We also compared seven Mermaid editors if you are choosing between those.

Frequently asked questions