{"id":5497,"library":"sphinxcontrib-svg2pdfconverter","title":"Sphinx SVG to PDF or PNG Converter Extension","description":"This extension converts SVG images to PDF or PNG when Sphinx builders do not natively support SVG images (e.g., LaTeX). It leverages external tools like Inkscape, rsvg-convert (from libRSVG), or CairoSVG for the conversion. The library is currently at version 2.1.0 and is actively maintained with updates released as needed to support Sphinx versions and conversion tools.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter","tags":["Sphinx","documentation","SVG","PDF","PNG","converter","extension","LaTeX"],"install":[{"cmd":"pip install sphinxcontrib-svg2pdfconverter","lang":"bash","label":"Basic Installation"},{"cmd":"pip install sphinxcontrib-svg2pdfconverter[CairoSVG]","lang":"bash","label":"With CairoSVG Backend"}],"dependencies":[{"reason":"Required Sphinx documentation generator extension","package":"Sphinx","version":">=1.6.3"},{"reason":"Optional backend for SVG conversion, installed via extra `[CairoSVG]`","package":"cairosvg","version":">=1.0","optional":true}],"imports":[{"note":"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.","wrong":"from sphinxcontrib.svg2pdfconverter import Converter","symbol":"Extension Activation","correct":"extensions = ['sphinxcontrib.inkscapeconverter'] # or .rsvgconverter, .cairosvgconverter"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\n\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Sphinx Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.cairosvgconverter', # Choose your backend: inkscapeconverter, rsvgconverter, or cairosvgconverter\n]\n\n# Example: Configure path for Inkscape if not in PATH (uncomment and adjust as needed)\n# inkscape_converter_bin = '/usr/local/bin/inkscape'\n\n# Example: Configure rsvg-convert (uncomment and adjust as needed)\n# rsvg_converter_bin = '/usr/bin/rsvg-convert'\n# rsvg_converter_format = 'pdf1.5' # Recommended for LaTeX compatibility\n","lang":"python","description":"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`."},"warnings":[{"fix":"Install 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.","message":"This 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add only one of `sphinxcontrib.inkscapeconverter`, `sphinxcontrib.rsvgconverter`, or `sphinxcontrib.cairosvgconverter` to your `conf.py` `extensions` list.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 2.0.0 or later: `pip install --upgrade sphinxcontrib-svg2pdfconverter`.","message":"Support 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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Add `rsvg_converter_format = 'pdf1.5'` to your `conf.py` if using `sphinxcontrib.rsvgconverter`.","message":"When 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`.","severity":"gotcha","affected_versions":"All versions, especially with newer `rsvg-convert`"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}