Registry /
devops / sphinxcontrib-svg2pdfconverter
Install & Compatibility
Where this runs
tested against v2.1.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.2s · import 0.000s · 93MB
99MB installed
● package 99MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Extension Activation
✓ extensions = ['sphinxcontrib.inkscapeconverter'] # or .rsvgconverter, .cairosvgconverter
✗ from sphinxcontrib.svg2pdfconverter import Converter
The extension is enabled by adding its module name as a string to the `extensions` list in Sphinx's `conf.py`, not by directly importing a Python class.
To use `sphinxcontrib-svg2pdfconverter`, you enable one of its backend-specific extensions in your Sphinx project's `conf.py` file. This example uses `cairosvgconverter`, which is often the easiest to set up due to its Pythonic nature, but still requires `libcairo` on the system. Remember to install the `[CairoSVG]` extra for `cairosvg`.
# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
project = 'My Sphinx Project'
copyright = '2026, Your Name'
author = 'Your Name'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinxcontrib.cairosvgconverter', # Choose your backend: inkscapeconverter, rsvgconverter, or cairosvgconverter
]
# Example: Configure path for Inkscape if not in PATH (uncomment and adjust as needed)
# inkscape_converter_bin = '/usr/local/bin/inkscape'
# Example: Configure rsvg-convert (uncomment and adjust as needed)
# rsvg_converter_bin = '/usr/bin/rsvg-convert'
# rsvg_converter_format = 'pdf1.5' # Recommended for LaTeX compatibility
Debug
Known issues
gotchaThis library acts as a wrapper around external tools (Inkscape, rsvg-convert, or CairoSVG). You must install these underlying conversion tools and ensure they are accessible in your system's PATH, or configure their paths in `conf.py`. The `[CairoSVG]` extra will install the Python `cairosvg` package, but `cairosvg` itself has system dependencies (like `libcairo`) that are not automatically handled by `pip`.fixInstall Inkscape, `librsvg2-bin` (for `rsvg-convert`), or `cairosvg` and its system dependencies. Configure `inkscape_converter_bin`, `rsvg_converter_bin` if tools are not in PATH. Consult CairoSVG documentation for its system dependencies.
affects: All versions
gotchaThe choice of conversion backend (Inkscape, rsvg-convert, or CairoSVG) is determined by which specific extension you add to your `conf.py`'s `extensions` list (e.g., `sphinxcontrib.inkscapeconverter`, `sphinxcontrib.rsvgconverter`, `sphinxcontrib.cairosvgconverter`). There is no single `sphinxcontrib.svg2pdfconverter` entry to configure the backend.fixAdd only one of `sphinxcontrib.inkscapeconverter`, `sphinxcontrib.rsvgconverter`, or `sphinxcontrib.cairosvgconverter` to your `conf.py` `extensions` list.
affects: All versions
breakingSupport for converting SVG images to PNG (in addition to PDF) was added in version 2.0.0. If your project requires PNG output, ensure you are using `sphinxcontrib-svg2pdfconverter` version 2.0.0 or newer.fixUpgrade to version 2.0.0 or later: `pip install --upgrade sphinxcontrib-svg2pdfconverter`.
affects: <2.0.0
gotchaWhen using the `rsvgconverter` backend, specifying `rsvg_converter_format = 'pdf1.5'` in `conf.py` is recommended. This format often generates fewer warnings and offers better compatibility with LaTeX backends, especially with newer versions of `rsvg-convert`.fixAdd `rsvg_converter_format = 'pdf1.5'` to your `conf.py` if using `sphinxcontrib.rsvgconverter`.
affects: All versions, especially with newer `rsvg-convert`
Upgrade
Version history
2.1.0latest on PyPI · released Mar 5, 2026
Audit
Dependencies
SphinxrequiredRequired Sphinx documentation generator extension
cairosvgoptionalOptional backend for SVG conversion, installed via extra `[CairoSVG]`