Mermaid to PNG: 4 Ways to Export Diagram Images
November 11, 2026 · 9 min read
Mermaid to PNG: 4 Ways to Export Diagrams as Images
You can convert Mermaid to PNG four ways: our browser-based Mermaid diagram tool, mermaid.live, the mmdc command or the Mermaid Preview extension for VS Code. All four rasterize the same diagram code. They differ in setup, resolution control and background options, so here's how to run each one and keep the image sharp.
PNG or SVG: Pick the Image Format Before You Export
A PNG is a fixed grid of pixels, so it pastes anywhere: Slack, Google Slides, a social post or any app that rejects SVG files. An SVG stays vector, so it scales without blur and suits documentation sites and print. Most of the methods below export both, so you can decide per destination. For one common destination, see our guide to adding a Mermaid diagram in Confluence.
Every method in this guide uses the same sample flowchart. If the syntax is new to you, our guide to Mermaid diagrams in Markdown explains diagram types, nodes and arrows.
flowchart LR
A[Write Mermaid code] --> B{Need a vector file?}
B -- Yes --> C[Export SVG]
B -- No --> D[Choose a scale]
D --> E[Export PNG]
E --> F[Paste into slides]
Inside a mermaid fence, that code draws a six-node, left-to-right flowchart with one decision point:
Save the same code, with no fence lines, as export-flow.mmd and the command-line examples below can read it.
How Do You Export a Mermaid Diagram as PNG Online?
The quickest route needs no install at all. Our Mermaid tool runs the official Mermaid library in your browser and draws the PNG on a canvas there, so your diagram code isn't uploaded anywhere.
- Open the Mermaid PNG exporter and replace the starter code with yours, or load a sample from the Template menu.
- Pick a Theme if you want a fixed look for the image. Our guide to Mermaid JS themes shows what each built-in one looks like.
- Set PNG scale to 1x, 2x or 3x.
- Click Download PNG. For a vector file, click Download SVG, or Copy SVG to put the markup on your clipboard.
The scale multiplies the pixel dimensions. A diagram that renders 800 px wide comes out 1600 px wide at 2x. Browser-based tools on this site are unlimited, so you can tweak a label and re-export as often as you need. If you'd rather paste the code into a README, Copy markdown block wraps it in a mermaid fence.
Download a PNG From mermaid.live
mermaid.live is the Mermaid project's own online editor. Paste your code into the code pane, then open the Actions panel.
The PNG size toggle has three modes. Auto exports at twice the diagram's rendered size. Width and Height let you type an exact pixel value (the box starts at 1080), and the other side scales to keep the aspect ratio. Click PNG or SVG to download, or Copy Image to put the PNG on your clipboard in browsers that support it.
The download is drawn in your browser, and the PNG gets a solid background in the editor's theme color. The small link icon beside the PNG button works differently. It opens a mermaid.ink address, a server that renders the image from the diagram code encoded in the URL. Stick with the download button for private diagrams.
Convert Mermaid to PNG on the Command Line With mmdc
For docs builds, CI jobs or a folder full of diagrams, use mmdc, the command from the official mermaid-cli package. Version 12.2.0 needs Node.js 22.13 or later. It renders through Puppeteer, which drives a headless Chrome, so the first install is a sizeable download.
npm install -g @mermaid-js/mermaid-cli
mmdc -i export-flow.mmd -o export-flow.png
The first line installs the mmdc binary globally. The second reads the diagram file and writes a PNG. The output extension picks the format, and if you leave out -o you get an SVG next to the input file.
Watch out for outdated advice. Older gists and some AI answers still say npm i -g mermaid.cli, but that package's last stable release was 0.5.1 in 2018. npm marks it deprecated in favor of @mermaid-js/mermaid-cli. They also suggest a --width flag, which the 12.2.0 CLI doesn't have.
These are the flags that matter for image output:
mmdc -i export-flow.mmd -o export-flow@2x.png -s 2 -b transparent
mmdc -i export-flow.mmd -o export-flow-dark.png -t dark --size 3000
npx -p @mermaid-js/mermaid-cli mmdc -i export-flow.mmd -o export-flow.png
The first command doubles the pixel density (-s is the Puppeteer scale factor, default 1) and drops the default white background. The second applies the dark theme and tries to make the longer side 3000 px. The README warns that --size may not work for every diagram type. The third runs mmdc through npx with no global install.
No Node on the machine? The Docker image looks for input files in /data, so mount your diagram folder there:
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD":/data minlag/mermaid-cli -i export-flow.mmd -o export-flow.png
Two more options help inside projects. Point -i at a Markdown file, such as mmdc -i README.template.md -o README.md, and mmdc renders each mermaid fence to an SVG file and swaps in image links. In a Python project, you can call mmdc through subprocess.run, since mermaid-cli is a Node tool.
Export Mermaid Diagrams as Images From VS Code
Since VS Code 1.121 (May 2026), the built-in Markdown preview renders mermaid fences. Microsoft merged the Markdown Preview Mermaid Support extension into the editor, per the VS Code 1.121 release notes. You can pan, zoom and copy the source, but the notes mention no way to save the diagram as an image.
For export, install Mermaid Preview (extension ID vstirbu.vscode-mermaid-preview), which the Mermaid team now maintains. Version 2.2.1 is free and needs no account. Open a .mmd file or a Markdown file with a mermaid fence, then run Mermaid Preview: Preview Diagram from the Command Palette. Use the export option in the preview to save a PNG or SVG.
Its README doesn't list a resolution or background setting for exports, so switch to mmdc when you need exact pixel sizes. For installing and managing extensions in general, see our VS Code Markdown guide.
How Do You Get a High-Resolution PNG From Mermaid?
Blurry diagrams usually come from a 1x export viewed on a high-density screen or stretched across a slide. The fix is more pixels at export time, because enlarging a small PNG afterwards only makes the blur bigger. Here's what each method lets you control:
| Method | Install | PNG size control | Transparent background | Best for |
|---|---|---|---|---|
| Our Mermaid tool | None | PNG scale 1x, 2x or 3x | No, solid fill | One-off images |
| mermaid.live | None | Auto (2x) or exact width or height in px | No, solid fill | Quick edits in the official editor |
| mmdc (mermaid-cli) | Node.js 22.13+ | -s scale factor, --size in px | Yes, -b transparent | Builds, CI, many files |
| VS Code Mermaid Preview | VS Code extension | Not documented | Not documented | Diagrams you already edit in VS Code |
We prefer 2x for slides and chat, and SVG for anything that will be printed. Save 3x for very large diagrams that people will zoom into.
Rendering can also differ slightly between methods. Each one bundles its own Mermaid release, so a brand-new diagram type may draw in one and fail in another.
Which Mermaid to PNG Method Fits Your Workflow?
Match the method to how often you export and where the code lives:
- One image for a slide, doc or chat message: the browser tool, with nothing to install.
- Iterating in the official editor: mermaid.live, as long as a solid background is fine.
- Docs builds, CI or dozens of diagrams: mmdc, or its Docker image on machines without Node.
- Diagrams you already edit in VS Code: the Mermaid Preview extension.
One gap catches people out. GitHub renders mermaid fences in READMEs, issues and pull requests, but its docs describe rendering only, not saving the diagram as an image. A screenshot works in a pinch, though it's capped at your screen's resolution.
If the end goal is a document rather than an image, skip the PNG step. Our Markdown to PDF guide covers PDF output, and the Markdown to Word converter turns Mermaid fences into PNG images inside the .docx file. That conversion runs on our server and uses one of the three free daily operations.
Mermaid PNG Export Questions
For most people, Mermaid to PNG is a two-minute job: paste the code, choose a scale, download. Reach for mmdc when diagrams live in a repo and need rebuilding on every change, and keep SVG for anything printed. To export your first diagram right now, open the Mermaid diagram tool, set the PNG scale to 2x and click Download PNG.