pycairo

library1.29.1pypypiunverified

Pycairo is a Python module providing bindings for the cairo graphics library. It enables Python programs to create high-quality vector graphics that scale without loss of clarity and can be output in various formats like PNG, SVG, PDF, and PostScript. The library is actively maintained with regular releases, typically multiple per year, following semantic versioning since v1.11.0. It currently supports Python 3.10+ and PyPy3.

serialization

pip install pycairo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYCAIRO

pycairo

serializationpythonv1.29.1

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

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.910 runs

build_error

glibc

py 3.10–3.910 runs

build_error

Code

Verified usage

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

cairo

✓ import cairo

This quickstart code creates an ImageSurface and a Context object, then draws a Bezier curve with guide lines, and finally saves the output to a PNG file. This demonstrates basic surface and context creation, drawing commands, and outputting to a file.

import cairo import math WIDTH, HEIGHT = 256, 256 surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT) ctx = cairo.Context(surface) ctx.scale(WIDTH, HEIGHT) ctx.set_line_width(0.04) # Draw a curve x, y, x1, y1 = 0.1, 0.5, 0.4, 0.9 x2, y2, x3, y3 = 0.6, 0.1, 0.9, 0.5 ctx.move_to(x, y) ctx.curve_to(x1, y1, x2, y2, x3, y3) ctx.stroke() # Draw guide lines ctx.set_source_rgba(1, 0.2, 0.2, 0.6) # Red with transparency ctx.set_line_width(0.02) ctx.move_to(x, y) ctx.line_to(x1, y1) ctx.move_to(x2, y2) ctx.line_to(x3, y3) ctx.stroke() surface.write_to_png("example.png") print("Generated example.png")

Debug

Known issues

breakingPycairo v1.29.0 drops support for Python 3.9 and PyPy 3.10. Ensure your Python environment is 3.10 or newer.

fix

Upgrade your Python interpreter to 3.10+ or PyPy3.11+ before upgrading Pycairo.

affects: >=1.29.0

breakingIn Pycairo v1.28.0, the `Path.__iter__()` method now returns a `PathDataType` (an integer subtype) instead of a raw `int`. Code relying on the exact type returned should be updated.

fix

Adjust type expectations or comparisons for the return value of `Path.__iter__()` to account for `PathDataType`.

affects: >=1.28.0

deprecatedCalling `ImageSurface.get_data()` on an already 'finished' surface now emits a `DeprecationWarning` in v1.28.0. In a future version, this will raise an exception.

fix

Ensure `ImageSurface.get_data()` is called only on active surfaces. Avoid calling it after `Surface.finish()` has been invoked or the underlying surface is destroyed.

affects: >=1.28.0

gotchaInstalling Pycairo often fails if the underlying C `cairo` graphics library and its development headers (e.g., `libcairo2-dev`) and `pkg-config` are not already present on the system. `pip install pycairo` alone is usually insufficient.

fix

Install the necessary system dependencies *before* running `pip install pycairo`. For example, on Debian/Ubuntu: `sudo apt install libcairo2-dev pkg-config python3-dev`; on macOS with Homebrew: `brew install cairo pkg-config`.

affects: All versions

gotchaCairo `Context` objects (and their paths, fills) are not persistent across drawing operations, especially for GUI surfaces. Drawings must be regenerated in their entirety during expose or redraw events, rather than relying on previous states.

fix

Design drawing logic to be fully re-executable. Store high-level drawing parameters (e.g., coordinates, colors) in application state and use them to redraw the entire scene whenever a redraw is needed. Do not expect `Context` state to persist indefinitely.

affects: All versions

gotchaIf the system's `cairo` C library version changes, or if `pycairo` was built against a different `cairo` version than is currently active, `pip` might use a cached wheel that causes runtime errors. This can manifest as unexpected `ImportError` or other C-level linking issues.

fix

Force `pip` to rebuild and reinstall `pycairo` by running: `pip install --force-reinstall --no-cache-dir pycairo`. This ensures `pycairo` is linked against the currently installed `cairo` library.

affects: All versions

Upgrade

Version history

1.29.1latest on PyPI · released Aug 7, 2026

Audit

Dependencies

cairorequiredPycairo is a Python binding for the cairo C graphics library, which must be installed on the system along with its development headers.

pkg-configrequiredRequired for `pycairo` to locate the `cairo` C library during installation.

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/pygobject/pycairo ↗

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

homepagehttps://pycairo.readthedocs.io ↗