{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}