{"id":2753,"library":"rlpycairo","title":"rlpycairo","description":"rlpycairo is a plugin backend renderer for the `reportlab.graphics.renderPM` module, designed to replace the legacy `_renderPM` C extension which experienced issues with complex documents. It extends the ReportLab PDF Toolkit, enabling the creation of rich PDF documents and charts in various bitmap and vector formats. Currently at version 0.4.0, the library is in a 'Pre-Alpha' development status, with periodic updates.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/MrBitBucket/rlPyCairo-mirror","tags":["reportlab","graphics","rendering","cairo","pdf","plugin"],"install":[{"cmd":"pip install rlpycairo","lang":"bash","label":"Install rlpycairo"}],"dependencies":[{"reason":"rlpycairo is a plugin backend for the ReportLab PDF Toolkit.","package":"reportlab","optional":false},{"reason":"Provides Python bindings for the Cairo graphics library, which rlpycairo uses for rendering.","package":"pycairo","optional":false},{"reason":"Required for font handling and rendering.","package":"freetype-py","optional":false},{"reason":"Needed to produce images with this package, especially when rendering to bitmap formats. Can often be PIL instead.","package":"Pillow","optional":true}],"imports":[{"note":"rlpycairo is enabled by configuring ReportLab's rendering backend, rather than direct class/function imports from the rlpycairo package itself.","symbol":"renderPMBackend","correct":"import reportlab.rl_config\nreportlab.rl_config.renderPMBackend = 'rlPyCairo'"}],"quickstart":{"code":"from reportlab.lib.pagesizes import A4\nfrom reportlab.lib.units import inch\nfrom reportlab.graphics.shapes import Drawing, String\nfrom reportlab.graphics import renderPM\nimport reportlab.rl_config\nimport os\n\n# Enable rlPyCairo backend\nreportlab.rl_config.renderPMBackend = 'rlPyCairo'\n\n# Create a simple ReportLab drawing\nd = Drawing(200, 100)\nd.add(String(50, 50, \"Hello, rlPyCairo!\", fillColor='red'))\n\noutput_filename = 'hello_rlpycairo.png'\n# Render the drawing to a PNG file using the configured backend\nrenderPM.drawToFile(d, output_filename, 'PNG')\n\nprint(f\"Generated '{output_filename}' using rlPyCairo backend.\")\nprint(f\"File path: {os.path.abspath(output_filename)}\")","lang":"python","description":"This quickstart demonstrates how to configure ReportLab to use `rlpycairo` as its rendering backend and then generate a simple PNG image using ReportLab's graphics module. This verifies the `rlpycairo` plugin is active and functional."},"warnings":[{"fix":"Ensure system-level Cairo development packages are installed (e.g., `sudo apt-get install libcairo2-dev` on Debian/Ubuntu, `brew install cairo` on macOS).","message":"Installation of `pycairo` (a core dependency) often fails if the underlying Cairo graphics library and its development headers are not installed on the system (e.g., via `apt-get`, `brew`). `pip install pycairo` alone is frequently insufficient.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of potential performance or quality differences if your application heavily relies on scaled images or complex text rendering. Consider alternative backends or optimizations if these issues arise.","message":"The `rlPyCairo` backend is noted in its documentation to be inferior to the original `_renderPM` C extension in two specific areas: rendering scaled images and the speed of drawing text.","severity":"gotcha","affected_versions":"All"},{"fix":"Do not expect advanced Cairo features like transparency or complex patterns to be automatically supported or exposed through `rlPyCairo` at this time. Use ReportLab's native features or other rendering backends for such requirements.","message":"Currently, `rlPyCairo` does not fully utilize advanced `PyCairo` capabilities such as transparency or patterns, despite Cairo's underlying support for these features.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify `rlpycairo` is installed (`pip show rlpycairo`). Ensure `reportlab.rl_config.renderPMBackend = 'rlPyCairo'` is executed at an appropriate point in your application startup before any `reportlab.graphics.renderPM` calls.","message":"A `ModuleNotFoundError: No module named 'rlPyCairo'` can occur if the package is not correctly installed in the active environment, or if `reportlab.rl_config.renderPMBackend` is not set to `'rlPyCairo'` before rendering operations.","severity":"gotcha","affected_versions":"All"},{"fix":"Pin the exact version in your `requirements.txt` to mitigate unexpected changes (`rlpycairo==0.4.0`). Monitor project updates closely if upgrading to new pre-1.0.0 versions.","message":"The package is currently marked with a '2 - Pre-Alpha' development status on PyPI. This implies that its API may not be stable, and breaking changes could occur in minor or patch releases, though none are explicitly documented as of 0.4.0.","severity":"breaking","affected_versions":"< 1.0.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}