{"id":1408,"library":"cairocffi","title":"cffi-based cairo bindings for Python","description":"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.","status":"active","version":"1.7.1","language":"python","source_language":"en","source_url":"https://github.com/Kozea/cairocffi/","tags":["graphics","cffi","cairo","bindings","gui"],"install":[{"cmd":"pip install cairocffi","lang":"bash","label":"Install cairocffi"}],"dependencies":[{"reason":"cairocffi uses cffi to bind to the native Cairo library.","package":"cffi"}],"imports":[{"note":"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.","wrong":"import cairo","symbol":"cairo","correct":"import cairocffi as cairo"},{"note":"Specific Cairo classes can be imported directly from the cairocffi module.","symbol":"ImageSurface","correct":"from cairocffi import ImageSurface"}],"quickstart":{"code":"import cairocffi as cairo\nimport os\n\n# Create an image surface (200x100 pixels, ARGB32 format)\nsurface = cairo.ImageSurface(cairo.FORMAT_ARGB32, 200, 100)\nctx = cairo.Context(surface)\n\n# Draw a light gray background\nctx.set_source_rgb(0.8, 0.8, 0.8) # R, G, B values (0.0-1.0)\nctx.paint()\n\n# Set text color, font, and size\nctx.set_source_rgb(0, 0, 0) # Black\nctx.select_font_face('Sans', cairo.FONT_SLANT_NORMAL, cairo.FONT_WEIGHT_NORMAL)\nctx.set_font_size(24)\n\n# Move to position and show text\nctx.move_to(10, 60) # x, y coordinates\nctx.show_text(\"Hello, cairocffi!\")\n\n# Define output path\noutput_filename = \"hello_cairocffi.png\"\n\n# Write the surface content to a PNG file\nsurface.write_to_png(output_filename)\nprint(f\"Generated {output_filename}\")\n\n# Clean up (optional for ImageSurface, but good practice for other surfaces like PDF/SVG)\nsurface.finish()","lang":"python","description":"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."},"warnings":[{"fix":"If your code expects a `bytearray`, convert the `memoryview` explicitly: `bytearray(surface.get_data())`. Using `memoryview` directly is generally more efficient.","message":"Changed `ImageSurface.get_data()` return type from `bytearray` to `memoryview`.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"The Cairo C library must be installed on your system.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"For file-based surfaces (e.g., PDFSurface, SVGSurface), `surface.finish()` is crucial to ensure all drawing operations are flushed and the file is properly closed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `import cairocffi as cairo` to maintain API compatibility while using the correct module import path.","message":"While API compatible, `cairocffi` does not provide a module named `cairo` directly. Code written for `pycairo` using `import cairo` will fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.7.1':50 '2d':15 'aim':22 'allow':28 'api':24 'backend':45 'base':3,44 'bind':5,11,68 'bug':63 'built':18 'cairo':4,14,33,59,67 'cairocffi':8 'capabl':37 'cffi':2,20,43,66 'cffi-bas':1,42 'compat':25 'current':47 'develop':30 'driven':56 'fix':64 'graphic':16,36,65 'gui':69 'infrequ':54 'leverag':32 'librari':17 'minor':62 'modern':41 'new':58 'occur':53 'often':55 'power':35 'provid':9 'pycairo':27 'python':7,10,29 'releas':52 'use':19 'version':48,60","created_at":"2026-04-09T03:46:39.032660+00:00","updated_at":"2026-04-16T01:20:06.844434+00:00","problems":[{"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`.","cause":"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.","error":"OSError: library not found: 'cairo'"},{"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).","cause":"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.","error":"ModuleNotFoundError: No module named 'cairocffi'"},{"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.","cause":"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.","error":"AttributeError: module 'constants' has no attribute '_CAIRO_HEADERS'"},{"fix":"Upgrade `cairocffi` to its latest version: `pip install --upgrade cairocffi`. If the issue persists, try reinstalling it in a clean virtual environment.","cause":"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.","error":"ModuleNotFoundError: No module named 'cairocffi._generated'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.7.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.cairocffi.org","github":"https://github.com/Kozea/cairocffi","docs":"https://doc.courtbouillon.org/cairocffi/","changelog":"https://doc.courtbouillon.org/cairocffi/stable/changelog.html","pypi":"https://pypi.org/project/cairocffi/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["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"}}