Install & Compatibility
Where this runs
tested against v3.11.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PlantUMLMarkdownExtension
✓ from plantuml_markdown import PlantUMLMarkdownExtension
✗ import plantuml_markdown
This quickstart demonstrates how to convert Markdown text containing PlantUML diagrams into HTML using `plantuml-markdown`. It shows both the GitHub-style triple-backtick syntax and the `::uml::` block syntax. The example configures a remote PlantUML server via the `servers` option, which is the recommended approach for versions 3.11.0 and later. For MkDocs, the plugin is enabled and configured in `mkdocs.yml`.
import markdown
import os
# For local rendering, ensure 'plantuml' command is in PATH and Java/Graphviz are installed.
# For remote rendering, use a server.
# This example uses a remote server for simplicity.
# In a real application, consider using os.environ for sensitive URLs or more robust configuration.
plantuml_server = os.environ.get('PLANTUML_SERVER_URL', 'http://www.plantuml.com/plantuml')
markdown_text = """
# My Document with a PlantUML Diagram
Here's a simple sequence diagram:
```plantuml format="svg"
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another action
```
And another one, using the alternative ::uml:: syntax:
::uml:: format="png"
Goofy -> MickeyMouse: calls
Goofy <-- MickeyMouse: responds
::end-uml::
"""
md = markdown.Markdown(extensions=['plantuml_markdown'], extension_configs={
'plantuml_markdown': {
'servers': [plantuml_server], # Using the new 'servers' config, introduced in 3.11.0
'cachedir': 'plantuml_cache' # Optional: enable caching
}
})
html_output = md.convert(markdown_text)
print(html_output)
# Example for MkDocs (mkdocs.yml)
# plugins:
# - plantuml_markdown:
# servers:
# - http://www.plantuml.com/plantuml
# cachedir: plantuml_cache
Debug
Known issues
deprecatedThe `server` and `kroki_server` configuration options are deprecated starting from version 3.11.0.fixUse the new `servers` option, which accepts a list of server URLs, allowing for a pool of servers for remote rendering. For example: `servers: ['http://www.plantuml.com/plantuml', 'https://kroki.io/plantuml']`.
affects: >= 3.11.0
gotchaWhen using local PlantUML binary rendering, `plantuml-markdown` requires Java and Graphviz to be installed and the `plantuml` command to be available in your system's PATH. Without these, local rendering will fail.fixEnsure Java is installed, download `plantuml.jar`, and create a wrapper script (e.g., `/usr/local/bin/plantuml`) that executes `java -jar /path/to/plantuml.jar`. Also, install Graphviz and make sure the `plantuml` command is discoverable in your system's PATH.
affects: All versions
gotchaPrior to version 3.9.8, inline SVG output might have included an erroneous `ns0:` prefix on SVG tags, potentially causing rendering issues in some viewers.fixUpgrade to `plantuml-markdown` version 3.9.8 or later to resolve the `ns0:` prefix issue.
affects: < 3.9.8
gotchaInclude directives (`!include`) in PlantUML diagrams, especially when used with multiple `base_dir` paths, were subject to bugs in versions 3.10.0 through 3.10.4 regarding how included files were located.fixEnsure you are using `plantuml-markdown` version 3.10.5 or later for improved reliability when using `base_dir` with multiple paths or `!include` directives. Refer to the documentation for correct `base_dir` configuration.
affects: 3.10.0 - 3.10.4
gotchaVersion 3.11.0 contained a minor f-string formatting error that primarily affected Python versions older than 3.12, potentially leading to runtime issues.fixUpgrade to `plantuml-markdown` version 3.11.1 or later if you are running Python environments older than 3.12.
affects: 3.11.0 (on Python < 3.12)
Upgrade
Version history
3.11.2latest on PyPI · released Apr 18, 2026
Audit
Dependencies
MarkdownrequiredThis is a Markdown extension and requires the Python-Markdown library to function.
JavaoptionalRequired if using local PlantUML binary for rendering diagrams.
GraphvizoptionalRequired if using local PlantUML binary for rendering diagrams, as PlantUML relies on Graphviz for layout.