sphinxcontrib-drawio
Sphinx Extension to include draw.io files
Decision gist · record as of 2026-08-14
Yes, if you actively maintain diagrams in draw.io and want them version-controlled and auto-exported in your Sphinx docs. The extension is stable, actively maintained, has no security issues, and low install friction. The main gotcha is the external draw.io binary dependency and headless-mode setup on CI—plan for that upfront. Not suitable for Read the Docs hosting.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- The draw.io desktop binary must be installed and accessible in $PATH (or configured via drawio_binary_path).
- On headless/CI systems, Xvfb must be installed and drawio_headless set to 'auto' or True.
- Does not work on Read the Docs due to RTD's restrictions on external packages.
License · maintenance · safety
MIT (permissive) — MIT license (permissive) means you can use, modify, and distribute this extension freely in both open and closed projects with minimal restrictions.
last release 2023-09-12 (1067 days) · last repo commit 2026-04-13 · 42 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 87,467 downloads/mo, #13,795 on PyPI
Alternatives
Verify before relying
pip install sphinxcontrib-drawio
# In conf.py:
extensions = ["sphinxcontrib.drawio"]
# In your .rst file:
.. drawio-image:: example.drawio
:export-scale: 150- Whether the extension handles multi-page .drawio files reliably when page-index or page-name options are used.
- Performance impact when exporting many large diagrams in a single documentation build.
- Compatibility with recent versions of draw.io desktop (last release was 2023-09-12).
What it is and what it does
sphinxcontrib-drawio is a Sphinx extension that lets you include draw.io diagrams directly in your documentation source. Instead of manually exporting diagrams to PNG or SVG and committing static images, you reference .drawio files in your reStructuredText using the drawio-image or drawio-figure directives, and the extension automatically exports them to your chosen format during the Sphinx build. It wraps the draw.io CLI tool and handles the mechanics of invoking it with the right options.
The extension is designed for projects that maintain diagrams in draw.io's native format and want those diagrams to stay in version control alongside the documentation source. It supports per-diagram export settings (format, scale, transparency, page selection) and builder-specific defaults, so you can export to SVG for HTML builds and PDF for LaTeX builds without duplicating directives. The main constraint is that it requires the draw.io desktop binary to be installed on the build machine, and on headless systems (CI, Docker) you need to configure virtual framebuffer support.
Use it for
- Maintain architecture diagrams, flowcharts, and UX mockups in draw.io and auto-export them to your Sphinx HTML/PDF documentation on each build.
- Configure different export formats per Sphinx builder (SVG for web, PDF for print) without editing source files.
- Scale diagrams to higher resolution for print output using the export-scale option.
- Include multi-page draw.io files and select specific pages by index or name for different sections of your docs.
- Run diagram export in CI/CD pipelines with headless mode and Xvfb for automated documentation builds.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you actively maintain diagrams in draw.io and want them version-controlled and auto-exported in your Sphinx docs.
The extension is stable, actively maintained, has no security issues, and low install friction. The main gotcha is the external draw.io binary dependency and headless-mode setup on CI—plan for that upfront. Not suitable for Read the Docs hosting.
Install
sphinxcontrib-drawio on PyPI
Before you install
Low friction: pure Python wheel with only sphinx as a runtime dependency. Active maintenance (last commit 2026-04-13) with no recent security issues. Requires the draw.io desktop binary in PATH and Xvfb on headless systems, which are external system dependencies, not Python-level friction.
The draw.io desktop binary must be installed and accessible in $PATH (or configured via drawio_binary_path). On headless/CI systems, Xvfb must be installed and drawio_headless set to 'auto' or True. Does not work on Read the Docs due to RTD's restrictions on external packages.
License in practice
MIT license (permissive) means you can use, modify, and distribute this extension freely in both open and closed projects with minimal restrictions.
Quickstart
pip install sphinxcontrib-drawio
# In conf.py:
extensions = ["sphinxcontrib.drawio"]
# In your .rst file:
.. drawio-image:: example.drawio
:export-scale: 150Verify before relying
- Whether the extension handles multi-page .drawio files reliably when page-index or page-name options are used.
- Performance impact when exporting many large diagrams in a single documentation build.
- Compatibility with recent versions of draw.io desktop (last release was 2023-09-12).
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.6 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 1 packagesphinx |
| Maintenance | Actively maintained 1,067 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 87,467 / month, #13,795 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Framework :: Sphinx :: ExtensionLicense :: OSI Approved :: MIT LicenseOperating System :: OS IndependentProgramming Language :: Python :: 3 |
Evidence: sphinxcontrib_drawio-0.0.17-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “sphinx drawio diagram extension”
- sphinxcontrib-drawioA Sphinx extension that embeds draw.io diagrams into documentation by…
- mkdocs-drawioA MkDocs plugin that embeds interactive Drawio diagrams directly into…
- sphinxcontrib-blockdiagA Sphinx extension that embeds block diagrams into documentation by…
Give your agent the search over MCP, or paste the wish link into any chat.
More Sphinx packages
Parses Python docstrings in ReST, Google, Numpydoc, and Epydoc formats, extracting structured information like descriptions, parameters, return types, and exceptions.
Install it if you need to programmatically read and extract structured data from Python docstrings.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
A Sphinx extension that converts documentation source files into QtHelp format, enabling integration with Qt-based help systems and documentation viewers.
However, be aware that maintenance is dormant—if you rely on it long-term, monitor Sphinx compatibility and consider whether QtHelp remains the right format for your…
See also mkdocs-drawio · sphinxcontrib-svg2pdfconverter · sphinxcontrib-blockdiag · sphinxcontrib-video · sphinxcontrib-plantuml · sphinxcontrib-mermaid · sphinxcontrib-programoutput · sphinx-substitution-extensions · swagger-plugin-for-sphinx · sphinxcontrib-youtube