---
id: plantuml-markdown
version: "3.11.2"
license: unclear
license_treatment: permissive
maintenance: active
---

# plantuml-markdown — A PlantUML plugin for Markdown

License: permissive · Maintenance: active · Downloads: 940.5K/mo

## What it is and what it does

This package extends Python-Markdown to recognize PlantUML diagram blocks and render them as images. You write diagram syntax in a Markdown code block using a special `::uml::` or ` ```plantuml ` delimiter, and the plugin converts it to an embedded PNG, SVG, or text representation in the final HTML. It supports both local PlantUML binaries (requiring Java and Graphviz) and remote rendering via PlantUML or Kroki servers, with options for image dimensions, CSS classes, alt text, and external file inclusion.

The plugin is a pure-Python wheel with no runtime dependencies, making it lightweight to install. Configuration is optional but recommended—you specify which rendering backend to use (local or remote), caching preferences, default image format, and other metadata. It integrates directly into the markdown_py command-line tool or Python-Markdown API.

Use it for:

- Generate architecture and sequence diagrams automatically from Markdown documentation without manual image creation.
- Embed UML diagrams in technical specifications or design documents that are version-controlled as plain text.
- Render diagrams in static site generators (Jekyll, Hugo, Sphinx) that use Markdown as input.
- Create interactive SVG diagrams with navigable links in HTML output when using svg_object or svg_inline formats.
- Include external PlantUML files in Markdown via the source parameter for modular diagram management.

## Worth the install?

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

A Markdown extension that converts PlantUML diagram syntax into rendered images (PNG, SVG, or text) embedded in HTML documents, using either a local PlantUML binary or a remote server.

Yes, if you use Markdown for documentation and want to embed UML diagrams without manual image creation. Install is frictionless and the package is actively maintained. Requires either a local PlantUML setup (Java + Graphviz) or network access to a remote server—factor that into your workflow before committing. No security issues reported.

## Install

pip install plantuml-markdown
uv add plantuml-markdown
poetry add plantuml-markdown

## Installing plantuml-markdown

Before you install: Low friction: pure Python wheel with no runtime dependencies. Active maintenance—last commit 2026-04-18, 226 repository stars. Requires external PlantUML binary or remote server access to function; not a standalone tool.

License in practice: Permissive license (BSD). No restrictions on commercial or private use; safe to include in proprietary projects.

Quickstart:

pip install plantuml-markdown

markdown_py -x plantuml_markdown mydoc.md > out.html

In mydoc.md:
::uml:: format="png"
  Alice -> Bob: Hello
  Bob --> Alice: Hi
::end-uml::

Requires PlantUML binary installed locally (with Java and Graphviz) or a configured remote PlantUML/Kroki server URL; Markdown processing requires Python-Markdown.

Verify before relying:

- Whether the package works with current Python-Markdown versions and any version constraints beyond 'requires_python >= 3.0'.
- Performance characteristics when rendering large diagrams or many diagrams in a single document.
- Whether caching (mentioned in config) actually improves rendering speed in typical workflows.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 940.5K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown plantuml diagram rendering, convert uml diagrams markdown, plantuml markdown extension, embed diagrams in markdown, markdown uml plugin, diagram to image markdown, plantuml server markdown, markdown-extension, diagram-rendering, documentation

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