sphinxcontrib-plantuml

What it is and what it does

sphinxcontrib-plantuml is a Sphinx extension that lets you write PlantUML diagrams inline in reStructuredText using the ``.. uml::`` directive, then automatically renders them as images during documentation builds. It depends on Sphinx and requires a working PlantUML installation (typically a Java JAR file) on your build system.

The extension supports multiple output formats—PNG, SVG, and PDF—and can generate different formats for HTML and LaTeX output. You configure it via Sphinx's conf.py, specifying the PlantUML executable path and output format preferences. It includes caching to avoid re-rendering unchanged diagrams and an experimental batch mode to reduce Java startup overhead when rendering many diagrams.

Use it for:

• Embed sequence diagrams, class hierarchies, and state machines directly in API or architecture documentation without maintaining separate image files.
• Generate consistent UML diagrams in both HTML and PDF versions of the same documentation from a single source.
• Document system design and component relationships in technical specifications alongside prose, keeping diagrams version-controlled with source.
• Reduce friction when updating diagrams by editing text in the documentation source rather than using a GUI tool and committing binary files.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds PlantUML diagram rendering to Sphinx documentation, letting you embed UML diagrams directly in reStructuredText source files and generate them as PNG, SVG, or PDF during builds.

Yes, if you already use Sphinx and have Java and PlantUML available on your build system. The extension is stable (Beta status, 133 GitHub stars, no known vulnerabilities) and widely used (top 15000 PyPI packages). High install friction is the main trade-off: you must set up PlantUML separately, and aging maintenance (last release 345 days ago) means updates may lag behind Sphinx releases, so test compatibility with your Sphinx version before deploying.

Install

sphinxcontrib-plantuml on PyPI

pip install sphinxcontrib-plantuml

uv add sphinxcontrib-plantuml

poetry add sphinxcontrib-plantuml

Installing sphinxcontrib-plantuml

Before you install

High install friction: requires Java (PlantUML runs on the JVM) and a working PlantUML installation or JAR file on your system, plus Sphinx as a runtime dependency. Last release was 345 days ago; maintenance status is aging but the repository is not archived and received a commit as recently as 2025-09-13.

License in practice

BSD license is permissive; you can use this extension in commercial and proprietary documentation projects without restriction, though you should retain the license notice.

Quickstart

pip install sphinxcontrib-plantuml

# In conf.py:
extensions = ['sphinxcontrib.plantuml']
plantuml = 'java -jar /path/to/plantuml.jar'

# In your .rst file:
.. uml::
   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

PlantUML requires Java and a PlantUML JAR file or executable in your PATH; you must configure the plantuml command in conf.py or install a wrapper script before Sphinx can render diagrams.

Verify before relying

• Whether the package works with modern Python versions (requires_python is unspecified in the fact sheet).
• Performance impact of batch rendering (marked EXPERIMENTAL in the description) on typical documentation builds.

Package facts

Evidence: sphinxcontrib_plantuml-0.31.tar.gz

Tags

More Utilities packages