cairosvg

library2.9.0pypypi✓ verified 26d ago

CairoSVG is a Python library that converts SVG files to other formats such as PNG, PDF, and EPS. It is built on top of the Cairo graphics library. The current version is 2.9.0, and it maintains a regular release cadence, including minor feature updates and critical security patches.

data serialization

pip install cairosvg

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · CAIROSVG

cairosvg

datapythonv2.9.0

Install

2.8s avg

Import

—

Disk

39MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.9.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 40.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.8s · import 0.000s · 42MB

39MB installed

● package 39MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

svg2png

✓ from cairosvg import svg2png

svg2pdf

✓ from cairosvg import svg2pdf

svg2svg

✓ from cairosvg import svg2svg

Used for 'fixing' SVG files or converting between SVG versions.

svg2eps

✓ from cairosvg import svg2eps

EPS export was added in version 2.5.0.

This quickstart demonstrates how to convert a simple SVG byte string to a PNG and a PDF file using `cairosvg.svg2png` and `cairosvg.svg2pdf`. The `bytestring` parameter expects bytes, and `write_to` expects a file-like object open in binary write mode.

import cairosvg import os # Example SVG content as a byte string svg_content_bytes = b''' <svg width="200" height="200" xmlns="http://www.w3.org/2000/svg"> <rect x="50" y="50" width="100" height="100" fill="red" /> <circle cx="100" cy="100" r="40" fill="yellow" /> </svg> ''' # Convert SVG to PNG and save to a file png_output_path = "output.png" with open(png_output_path, "wb") as f_png: cairosvg.svg2png(bytestring=svg_content_bytes, write_to=f_png) print(f"SVG converted to PNG: {png_output_path}") # Convert SVG to PDF and save to a file pdf_output_path = "output.pdf" with open(pdf_output_path, "wb") as f_pdf: cairosvg.svg2pdf(bytestring=svg_content_bytes, write_to=f_pdf) print(f"SVG converted to PDF: {pdf_output_path}") # Clean up generated files (optional) # os.remove(png_output_path) # os.remove(pdf_output_path)

cairosvg --version

Debug

Known issues

breakingCairoSVG frequently drops support for older Python versions. As of 2.9.0, Python 3.9 is no longer supported, requiring Python >=3.10. Earlier versions dropped support for Python 3.5, 3.6, 3.7, and 3.8.

fix

Upgrade your Python environment to at least 3.10 or ensure your CairoSVG version is compatible with your Python version. Always check the `requires_python` field on PyPI.

affects: >=2.5.0

breakingTo prevent denial-of-service (DoS) attacks, CairoSVG 2.9.0 introduced a hard limit of 100,000 recursively nested `<use>` tags. Documents exceeding this limit will stop rendering prematurely.

fix

For unusually large or complex documents with many `<use>` tags, use the `--unsafe` option on the command line or the `unsafe=True` parameter in conversion functions. Review your SVG structure to reduce excessive nesting if possible.

affects: >=2.9.0

breakingAs of CairoSVG 2.7.0, fetching external resources (like remote images or stylesheets) from SVGs is disabled by default due to security concerns. This can lead to missing content in converted outputs if external URLs are used.

fix

To allow fetching external resources, use the `--unsafe` option on the command line or pass `unsafe=True` or a custom `url_fetcher` parameter to the conversion functions. Exercise caution when enabling this option with untrusted SVG sources.

affects: >=2.7.0

breakingVersions prior to 2.5.1 were vulnerable to Regular Expression Denial of Service (ReDoS) attacks when processing malicious SVG files, potentially causing the process to hang indefinitely.

fix

Upgrade to CairoSVG 2.5.1 or newer immediately to mitigate ReDoS vulnerabilities. This is a critical security update.

affects: <2.5.1

breakingCairoSVG depends on the `cairo` graphics library, which must be installed as a system dependency. Without it, `cairocffi` (a core dependency of CairoSVG) will fail to load, leading to an `OSError` like 'no library called "cairo-2" was found' or 'libcairo.so.2: cannot open shared object file'.

fix

Install the necessary system dependencies for Cairo. On Debian/Ubuntu-based systems, this typically involves `sudo apt-get update && sudo apt-get install -y libcairo2-dev libffi-dev pkg-config`. For other operating systems, consult the CairoSVG or cairocffi documentation for specific package names.

affects: *

breakingCairoSVG relies on the cairo C library being installed on the system. If the cairo library or its development headers are not present, an OSError (e.g., 'no library called "cairo" was found') will occur, preventing CairoSVG from loading.

fix

Ensure the cairo C library and its development headers are installed on your system. For Debian/Ubuntu-based systems, install `libcairo2-dev`. For Alpine Linux, install `cairo-dev`. Other distributions may have different package names (e.g., `cairo-devel` on RHEL/Fedora).

affects: *

Errors

Common errors & fixes

OSError: no library called "cairo-2" was found

CairoSVG relies on the underlying Cairo graphics library, which is a system-level dependency (not a Python package) that could not be found or loaded by the `cairocffi` binding. This is common on Windows, macOS, and in containerized environments where system libraries are not pre-installed.

fix

Install the Cairo graphics library using your operating system's package manager. For macOS, use Homebrew (`brew install cairo`). For Windows, you typically need to install a GTK+ bundle that includes Cairo. For Debian/Ubuntu Linux, use `sudo apt-get install libcairo2 libffi-dev`. For Alpine Linux, use `apk add cairo-dev`.

ModuleNotFoundError: No module named 'CairoSVG'

The Python module name for CairoSVG is `cairosvg` (all lowercase), but the import statement uses incorrect capitalization. Python module imports are case-sensitive.

fix

Change the import statement from `import CairoSVG` to `import cairosvg`.

ModuleNotFoundError: No module named 'PIL'

CairoSVG uses the Pillow library (which imports as `PIL`) for handling embedded raster images within SVG files. This error occurs if Pillow is not installed or if there are issues with its installation or its underlying native dependencies (like `libjpeg` or `zlib`).

fix

Install Pillow by running `pip install Pillow`. If the error persists, you might need to install development headers for image libraries on your system, for example, `sudo apt-get install python3-dev libjpeg-dev zlib1g-dev` on Debian/Ubuntu, before reinstalling Pillow.

Upgrade

Version history

2.9.0latest on PyPI · released Mar 14, 2026

Audit

Dependencies

pycairorequiredPython bindings for the Cairo graphics library, essential for rendering.

PillowoptionalRequired for handling raster images embedded in SVGs.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Kozea/CairoSVG ↗

packagehttps://pypi.org/project/cairosvg/ ↗

homepagehttps://courtbouillon.org/cairosvg ↗

docshttps://cairosvg.org/documentation/ ↗