Install with pip:
pip install cairocffi
This will automatically install CFFI, which on CPython requires python-dev and libffi-dev. See the CFFI documentation for details.
The module to import is named cairocffi in order to co-exist peacefully with Pycairo which uses cairo, but cairo is shorter and nicer to use:
import cairocffi as cairo
cairocffi will dynamically load cairo as a shared library at this point. If it fails to find it, you will see an exception like this:
OSError: library not found: 'cairo'
Make sure cairo is correctly installed and available through your system’s usual mechanisms. On Linux, the LD_LIBRARY_PATH environment variable can be used to indicate where to find shared libraries.
cairocffi needs a libcairo-2.dll file in a directory that is listed in the PATH environment variable.
Alexander Shaduri’s GTK+ installer works. (Make sure to leave the Set up PATH environment variable checkbox checked.) Pycairo on Windows is sometimes compiled statically against cairo and may not provide a .dll file that cairocffi can use.
The same cairocffi version can be used with a variety of cairo version. For example, the Surface.set_mime_data() method is based on the cairo_surface_set_mime_data() C function, which is only available since cairo 1.10. You will get a runtime exception if you try to use it with an older cairo. You can however still use the rest of the API. There is no need for cairocffi’s versions to be tied to cairo’s versions.
Use cairo_version() to test the version number:
if cairo.cairo_version() > 11000: surface.set_mime_data('image/jpeg', jpeg_bytes)
cairocffi is tested with both cairo 1.8.2 and the latest (1.12.8 as of this writing.)
cairocffi’s Python API is compatible with Pycairo. Please file a bug if you find incompatibilities.
In your own code that uses Pycairo, you should be able to just change the imports from import cairo to import cairocffi as cairo as above. If it’s not your own code that imports Pycairo, the install_as_pycairo() function can help:
import cairocffi cairocffi.install_as_pycairo() import cairo assert cairo is cairocffi
Alternatively, add a cairo.py file somewhere in your sys.path, so that it’s imported instead of pycairo:
from cairocffi import *
It is also possible to convert pycairo contexts to cairocffi.
For doing something useful with cairo, you need at least a surface and a context:
surface = cairo.ImageSurface(cairo.FORMAT_RGB24, 300, 200) context = cairo.Context(surface) with context: context.set_source_rgb(1, 1, 1) # White context.paint() # Restore the default source which is black. context.move_to(90, 140) context.rotate(-0.5) context.set_font_size(20) context.show_text(u'Hi from cairo!') surface.write_to_png('example.png')
The Surface represents the target. There are various types of surface for various output backends. The Context holds internal state and is use for drawing. We’re only using solid colors here, but more complex Pattern types are also available.
All the details are in Python API reference.