cairocffi requires CFFI, which can be installed with pip but has its own dependencies that can be tricky to install.
- On Linux, install
libffi-devfrom your system’s package manager.
- On OS X, install
libffi, for example with Homebrew. You may need to set the PKG_CONFIG_PATH environment variable.
- On Windows, consider using Christoph Gohlke’s unofficial binary builds.
See CFFI’s own documentation for details.
Install with pip:
pip install cairocffi
This will automatically install CFFI.
pip install cairocffi[xcb]
In addition to other dependencies, this will install xcffib.
The module to import is named
in order to co-exist peacefully with Pycairo which uses
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
On Linux, the
LD_LIBRARY_PATH environment variable can be used to indicate
where to find shared libraries.
Installing cairo on Windows¶
cairocffi needs a
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.
Cairo, pycairo, and cairocffi each have version numbers. The same cairocffi
version can be used with a variety of cairo versions. 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.
cairo_version() to test the version number for cairo:
if cairocffi.cairo_version() > 11000: surface.set_mime_data('image/jpeg', jpeg_bytes)
Here are all the version numbers:
>>> print("The cairo version is %s, meaning %s." ... % (cairocffi.cairo_version(), cairocffi.cairo_version_string()) The cairo version is 11402, meaning 1.14.02. >>> print("The latest pycairo version this cairocffi version is compatible with is %s." ... % cairo.version) The latest pycairo version this cairocffi version is compatible with is 1.10.0. >>> print("The cairocffi version is %s." % cairo.VERSION) The cairocffi version is 0.7.2
cairocffi is automatically tested with both cairo 1.13.0 (Ubuntu Trusty’s default version) and manually tested with the latest (1.15.12 as of this writing.)
Compatibility with Pycairo¶
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,
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
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:
import cairocffi as cairo surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, 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('Hi from cairo!') surface.write_to_png('example.png')
Surface represents the target.
There are various types of surface for various output backends.
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.