Install & Compatibility
Where this runs
tested against v0.31 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.9s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.plantuml
✓ extensions = ['sphinxcontrib.plantuml']
To enable the extension, add 'sphinxcontrib.plantuml' to the 'extensions' list in your Sphinx conf.py file.
To quickly get started, first, create a Sphinx project. Then, modify your `conf.py` to include `sphinxcontrib.plantuml` in your `extensions` list. Crucially, ensure that the PlantUML Java executable is either in your system's PATH or explicitly configured using the `plantuml` variable in `conf.py`. Finally, embed PlantUML code directly into your reStructuredText files using the `.. uml::` directive.
# conf.py
import os
project = 'My Project'
copyright = '2026, Your Name'
extensions = [
'sphinxcontrib.plantuml',
]
# Configure PlantUML executable path (essential if not in PATH)
# Replace '/path/to/plantuml.jar' with the actual path.
# If 'plantuml' command is in your system PATH, this line can be omitted.
# plantuml = 'java -jar /path/to/plantuml.jar'
# Optional: Set output format (default is 'png' for HTML)
# plantuml_output_format = 'svg_img'
# index.rst (or a new .rst file)
# Add the following to your .rst file:
# .. uml::
# @startuml
# Alice -> Bob: Hello
# Bob -> Alice: Hi!
# @enduml
# To build the documentation:
# sphinx-build -b html . _build/html
Debug
Known issues
breakingThe `sphinxcontrib-plantuml` extension itself is merely a Python wrapper for Sphinx. It *requires* PlantUML (the Java application) and a Java Runtime Environment (JRE) to be installed separately on the system where Sphinx builds are performed. Without these, diagrams cannot be rendered, leading to build failures or 'unknown directive' errors.fixInstall PlantUML and a compatible JRE. Download `plantuml.jar` from the official PlantUML website and install Java (e.g., OpenJDK). Ensure the `java` command and `plantuml.jar` are accessible.
affects: All versions
gotchaIf the `plantuml` command is not in your system's PATH, you must explicitly configure its full command in `conf.py`. Failing to do so will result in Sphinx being unable to find and execute PlantUML.fixAdd `plantuml = 'java -jar /path/to/plantuml.jar'` to your `conf.py`, replacing `/path/to/plantuml.jar` with the actual location of the PlantUML executable JAR file.
affects: All versions
gotchaPlantUML can sometimes silently fall back to generating PNG images, even when another format (like SVG) is requested, for example, when certain diagram types (e.g., ditaa) are included. This silent fallback can cause unexpected encoding errors in `sphinxcontrib-plantuml` if it expects a specific output format.fixExplicitly define the expected output format using `plantuml_output_format` and ensure your PlantUML code is compatible with the desired output. Check PlantUML's own error logs for issues with diagram generation.
affects: 0.20.1 and potentially other versions
gotchaFor HTML output, the default `plantuml_output_format` is `png`. If using SVG, `svg_obj` (embedding with `<object/>`) might lead to scaling issues in some browsers. For better responsiveness, `svg_img` (embedding with `<img/>`) is often preferred. For LaTeX/PDF output, `png` quality can be poor; `svg_pdf` (requires `sphinxcontrib-svg2pdfconverter` or similar) or `eps_pdf` (requires `epstopdf`) is recommended.fixSet `plantuml_output_format = 'svg_img'` in `conf.py` for responsive SVG in HTML. For high-quality PDF, configure `plantuml_latex_output_format = 'pdf'` (which uses `svg_pdf` or `eps_pdf` if converters are available) and ensure necessary converters like `sphinxcontrib-svg2pdfconverter` or `epstopdf` are installed.
affects: All versions
deprecatedOlder versions of `sphinxcontrib-plantuml` had compatibility issues with newer Sphinx 4.x releases and Python 3.13 due to internal API changes in Sphinx and Python's `inspect` module.fixAlways use the latest stable version of `sphinxcontrib-plantuml` (0.31 or newer) to ensure compatibility with recent Sphinx and Python releases. Upgrade `pip install --upgrade sphinxcontrib-plantuml`.
affects: < 0.28 (Sphinx 4.x issues), potentially older versions for Python 3.13
Upgrade
Version history
0.31latest on PyPI · released Sep 3, 2025
Audit
Dependencies
PlantUMLrequiredRequired Java application for rendering diagrams. Must be installed separately and accessible via PATH or configured in conf.py.
Java Runtime Environment (JRE)requiredRequired to run PlantUML. Must be installed separately.