{"id":1409,"library":"cairosvg","title":"CairoSVG","description":"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.","status":"active","version":"2.9.0","language":"python","source_language":"en","source_url":"https://github.com/Kozea/CairoSVG/","tags":["svg","converter","pdf","png","eps","graphics","cairo"],"install":[{"cmd":"pip install cairosvg","lang":"bash","label":"Install CairoSVG"},{"cmd":"sudo apt-get install libcairo2-dev # Debian/Ubuntu\nbrew install cairo # macOS\n# Other OS may require manual Cairo installation","lang":"bash","label":"Install Cairo (OS-level dependency)"}],"dependencies":[{"reason":"Python bindings for the Cairo graphics library, essential for rendering.","package":"pycairo"},{"reason":"Required for handling raster images embedded in SVGs.","package":"Pillow","optional":true}],"imports":[{"symbol":"svg2png","correct":"from cairosvg import svg2png"},{"symbol":"svg2pdf","correct":"from cairosvg import svg2pdf"},{"note":"Used for 'fixing' SVG files or converting between SVG versions.","symbol":"svg2svg","correct":"from cairosvg import svg2svg"},{"note":"EPS export was added in version 2.5.0.","symbol":"svg2eps","correct":"from cairosvg import svg2eps"}],"quickstart":{"code":"import cairosvg\nimport os\n\n# Example SVG content as a byte string\nsvg_content_bytes = b'''\n<svg width=\"200\" height=\"200\" xmlns=\"http://www.w3.org/2000/svg\">\n  <rect x=\"50\" y=\"50\" width=\"100\" height=\"100\" fill=\"red\" />\n  <circle cx=\"100\" cy=\"100\" r=\"40\" fill=\"yellow\" />\n</svg>\n'''\n\n# Convert SVG to PNG and save to a file\npng_output_path = \"output.png\"\nwith open(png_output_path, \"wb\") as f_png:\n    cairosvg.svg2png(bytestring=svg_content_bytes, write_to=f_png)\nprint(f\"SVG converted to PNG: {png_output_path}\")\n\n# Convert SVG to PDF and save to a file\npdf_output_path = \"output.pdf\"\nwith open(pdf_output_path, \"wb\") as f_pdf:\n    cairosvg.svg2pdf(bytestring=svg_content_bytes, write_to=f_pdf)\nprint(f\"SVG converted to PDF: {pdf_output_path}\")\n\n# Clean up generated files (optional)\n# os.remove(png_output_path)\n# os.remove(pdf_output_path)","lang":"python","description":"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."},"warnings":[{"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.","message":"CairoSVG 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.","severity":"breaking","affected_versions":">=2.5.0"},{"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.","message":"To 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.","severity":"breaking","affected_versions":">=2.9.0"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=2.7.0"},{"fix":"Upgrade to CairoSVG 2.5.1 or newer immediately to mitigate ReDoS vulnerabilities. This is a critical security update.","message":"Versions 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.","severity":"breaking","affected_versions":"<2.5.1"},{"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.","message":"CairoSVG 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'.","severity":"breaking","affected_versions":"*"},{"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).","message":"CairoSVG 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.","severity":"breaking","affected_versions":"*"}],"env_vars":null,"search_vec":"'2.9.0':34 'built':22 'cadenc':41 'cairo':27,56 'cairosvg':1,2 'convert':8,51 'critic':47 'current':31 'ep':19,54 'featur':44 'file':10 'format':13 'graphic':28,55 'includ':42 'librari':6,29 'maintain':37 'minor':43 'patch':49 'pdf':17,52 'png':16,53 'python':5 'regular':39 'releas':40 'secur':48 'svg':9,50 'top':24 'updat':45 'version':32","created_at":"2026-04-09T03:46:41.614147+00:00","updated_at":"2026-04-16T01:20:46.226543+00:00","problems":[{"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`.","cause":"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.","error":"OSError: no library called \"cairo-2\" was found"},{"fix":"Change the import statement from `import CairoSVG` to `import cairosvg`.","cause":"The Python module name for CairoSVG is `cairosvg` (all lowercase), but the import statement uses incorrect capitalization. Python module imports are case-sensitive.","error":"ModuleNotFoundError: No module named 'CairoSVG'"},{"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.","cause":"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`).","error":"ModuleNotFoundError: No module named 'PIL'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.9.0","cli_name":"cairosvg","cli_version":"Traceback (most recent call last):","type":"library","homepage":"https://courtbouillon.org/cairosvg","github":"https://github.com/Kozea/CairoSVG","docs":"https://cairosvg.org/documentation/","changelog":null,"pypi":"https://pypi.org/project/cairosvg/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"stale"}}