{"id":2212,"library":"pycairo","title":"Pycairo","description":"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.","status":"active","version":"1.29.0","language":"en","source_language":"en","source_url":"https://github.com/pygobject/pycairo","tags":["graphics","drawing","vector-graphics","cairo","imaging"],"install":[{"cmd":"pip install pycairo","lang":"bash","label":"Basic installation (requires system dependencies)"},{"cmd":"sudo apt install libcairo2-dev pkg-config python3-dev","lang":"bash","label":"Ubuntu/Debian system dependencies (before pip install)"},{"cmd":"brew install cairo pkg-config","lang":"bash","label":"macOS/Homebrew system dependencies (before pip install)"},{"cmd":"sudo dnf install cairo-devel pkg-config python3-devel","lang":"bash","label":"Fedora system dependencies (before pip install)"},{"cmd":"pip install --force-reinstall --no-cache-dir pycairo","lang":"bash","label":"Force reinstall to avoid cache issues after cairo C library updates"}],"dependencies":[{"reason":"Pycairo is a Python binding for the cairo C graphics library, which must be installed on the system along with its development headers.","package":"cairo","optional":false},{"reason":"Required for `pycairo` to locate the `cairo` C library during installation.","package":"pkg-config","optional":false}],"imports":[{"symbol":"cairo","correct":"import cairo"}],"quickstart":{"code":"import cairo\nimport math\n\nWIDTH, HEIGHT = 256, 256\n\nsurface = cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT)\nctx = cairo.Context(surface)\n\nctx.scale(WIDTH, HEIGHT)\nctx.set_line_width(0.04)\n\n# Draw a curve\nx, y, x1, y1 = 0.1, 0.5, 0.4, 0.9\nx2, y2, x3, y3 = 0.6, 0.1, 0.9, 0.5\nctx.move_to(x, y)\nctx.curve_to(x1, y1, x2, y2, x3, y3)\nctx.stroke()\n\n# Draw guide lines\nctx.set_source_rgba(1, 0.2, 0.2, 0.6) # Red with transparency\nctx.set_line_width(0.02)\nctx.move_to(x, y)\nctx.line_to(x1, y1)\nctx.move_to(x2, y2)\nctx.line_to(x3, y3)\nctx.stroke()\n\nsurface.write_to_png(\"example.png\")\nprint(\"Generated example.png\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python interpreter to 3.10+ or PyPy3.11+ before upgrading Pycairo.","message":"Pycairo v1.29.0 drops support for Python 3.9 and PyPy 3.10. Ensure your Python environment is 3.10 or newer.","severity":"breaking","affected_versions":">=1.29.0"},{"fix":"Adjust type expectations or comparisons for the return value of `Path.__iter__()` to account for `PathDataType`.","message":"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.","severity":"breaking","affected_versions":">=1.28.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.28.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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"}