Pycairo

Warnings

• breaking Pycairo 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.
• breaking In 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`.
• deprecated Calling `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.
• gotcha Installing 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`.
• gotcha Cairo `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.
• gotcha If 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.

Install

• pip install pycairo Basic installation (requires system dependencies)
• sudo apt install libcairo2-dev pkg-config python3-dev Ubuntu/Debian system dependencies (before pip install)
• brew install cairo pkg-config macOS/Homebrew system dependencies (before pip install)
• sudo dnf install cairo-devel pkg-config python3-devel Fedora system dependencies (before pip install)
• pip install --force-reinstall --no-cache-dir pycairo Force reinstall to avoid cache issues after cairo C library updates

Imports

• cairo

  import cairo

Quickstart

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")