cairocffi

library1.7.1pypypi✓ verified 26d ago

cairocffi provides Python bindings for the Cairo 2D graphics library, built using CFFI. It aims for API compatibility with Pycairo, allowing Python developers to leverage Cairo's powerful graphics capabilities with a more modern CFFI-based backend. The current version is 1.7.1, with releases occurring infrequently, often driven by new Cairo versions or minor bug fixes.

serialization

pip install cairocffi

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CAIROCFFI

cairocffi

serializationpythonv1.7.1

Install

1.9s avg

Import

—

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.1 · 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 · 19.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.000s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

cairo

✓ import cairocffi as cairo

✗ import cairo

While cairocffi is API compatible with pycairo, the module name is different. The common practice is to import cairocffi and alias it as cairo for consistency.

ImageSurface

✓ from cairocffi import ImageSurface

Specific Cairo classes can be imported directly from the cairocffi module.

This quickstart demonstrates how to create an image surface, draw text onto it, and save the result as a PNG file. It highlights the typical import pattern and basic drawing operations using the Cairo API.

import cairocffi as cairo import os # Create an image surface (200x100 pixels, ARGB32 format) surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, 200, 100) ctx = cairo.Context(surface) # Draw a light gray background ctx.set_source_rgb(0.8, 0.8, 0.8) # R, G, B values (0.0-1.0) ctx.paint() # Set text color, font, and size ctx.set_source_rgb(0, 0, 0) # Black ctx.select_font_face('Sans', cairo.FONT_SLANT_NORMAL, cairo.FONT_WEIGHT_NORMAL) ctx.set_font_size(24) # Move to position and show text ctx.move_to(10, 60) # x, y coordinates ctx.show_text("Hello, cairocffi!") # Define output path output_filename = "hello_cairocffi.png" # Write the surface content to a PNG file surface.write_to_png(output_filename) print(f"Generated {output_filename}") # Clean up (optional for ImageSurface, but good practice for other surfaces like PDF/SVG) surface.finish()

Debug

Known issues

breakingChanged `ImageSurface.get_data()` return type from `bytearray` to `memoryview`.

fix

If your code expects a `bytearray`, convert the `memoryview` explicitly: `bytearray(surface.get_data())`. Using `memoryview` directly is generally more efficient.

affects: >=1.0.0

gotchaThe Cairo C library must be installed on your system.

fix

cairocffi binds to the native Cairo library. On Debian/Ubuntu, install `libcairo2-dev`. On Fedora, `cairo-devel`. On macOS with Homebrew, `brew install cairo`.

affects: All versions

gotchaFor file-based surfaces (e.g., PDFSurface, SVGSurface), `surface.finish()` is crucial to ensure all drawing operations are flushed and the file is properly closed.

fix

Always call `surface.finish()` on surfaces that write to files or other streams when you are done with them to prevent incomplete or corrupted output. For `ImageSurface`, it's less critical as data is held in memory, but still good practice.

affects: All versions

gotchaWhile API compatible, `cairocffi` does not provide a module named `cairo` directly. Code written for `pycairo` using `import cairo` will fail.

fix

Always use `import cairocffi as cairo` to maintain API compatibility while using the correct module import path.

affects: All versions

Errors

Common errors & fixes

OSError: library not found: 'cairo'

The underlying Cairo C graphics library is not installed on the system, or its shared libraries are not discoverable in the system's library paths (e.g., PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS) for `cairocffi` to load dynamically.

fix

Install the Cairo development libraries for your operating system. For Debian/Ubuntu: `sudo apt-get install libcairo2-dev`. For Fedora/RHEL: `sudo dnf install cairo-devel`. For macOS with Homebrew: `brew install cairo`. For Windows, install a GTK+ distribution (like MSYS2 or GTK+ for Windows Runtime Installer) which includes `libcairo-2.dll` and ensure its directory is in your system's PATH environment variable or set `CAIROCFFI_DLL_DIRECTORIES`.

ModuleNotFoundError: No module named 'cairocffi'

The `cairocffi` Python package is either not installed in the currently active Python environment, or there is a Python version mismatch where `pip` installed it for a different interpreter.

fix

Install `cairocffi` using pip, ensuring you use the correct `pip` executable for your Python environment (e.g., `pip3 install cairocffi` if using Python 3).

AttributeError: module 'constants' has no attribute '_CAIRO_HEADERS'

This error typically occurs during `cairocffi` installation or import when a local Python module named `constants.py` exists in the Python path and is mistakenly imported instead of `cairocffi`'s internal `constants` module, leading to a name collision.

fix

Rename your local `constants.py` file to avoid the naming conflict, or ensure that `cairocffi` is installed and run in an isolated virtual environment where such conflicts are less likely.

ModuleNotFoundError: No module named 'cairocffi._generated'

This issue usually indicates an outdated or corrupted installation of `cairocffi`, particularly when a dependent library (like `qtile`) requires a newer version or a regenerated internal module.

fix

Upgrade `cairocffi` to its latest version: `pip install --upgrade cairocffi`. If the issue persists, try reinstalling it in a clean virtual environment.

Upgrade

Version history

1.7.1latest on PyPI · released Jun 18, 2024

Audit

Dependencies

cffirequiredcairocffi uses cffi to bind to the native Cairo library.

Agent activity

11 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

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

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

homepagehttps://www.cairocffi.org ↗

docshttps://doc.courtbouillon.org/cairocffi/ ↗

changeloghttps://doc.courtbouillon.org/cairocffi/stable/changelog.html ↗