cairometal
A pycairo-compatible 2D vector-graphics library that rasterizes on the Apple GPU via Metal.
⚠️ Independent project — not affiliated with the cairo graphics library or the official
pycairobinding.cairometalre-implements a cairo-compatible surface/context drawing API on top of Apple Metal; it does not wrap or link the cairo C library.
pip install cairometal
import cairometal as cairo
s = cairo.ImageSurface(cairo.FORMAT_ARGB32, 256, 256)
ctx = cairo.Context(s)
ctx.set_source_rgb(0.13, 0.42, 0.96); ctx.paint() # GPU
ctx.set_source_rgb(1, 1, 1); ctx.rectangle(48, 48, 160, 160); ctx.fill()
s.write_to_png("out.png")
At a glance
| What | cairo's 2D drawing model (paths, fills, strokes, gradients, text, clips, groups, PNG) rasterized on the GPU through Metal |
| Platform | macOS, Apple Silicon (arm64) |
| Python | 3.10 – 3.14 (per-version wheels; the extension is not abi3) |
| Install | prebuilt wheels — no compiler needed at install time |
| API | mirrors pycairo — for most code, import cairometal as cairo is the only change |
| License | MIT |
It began as the GPU rendering engine inside an offline iOS Python IDE (where cairo is used for plotting and animation), and is published here as a standalone, pip-installable package for the desktop.
Installation
pip install cairometal
- Wheels are published per CPython version for macOS
arm64— you get a prebuilt binary, nothing is compiled at install time. - If pip can't find a wheel for your interpreter it falls back to building the sdist, which requires a macOS host with full Xcode (the Metal shader compiler
xcrun -sdk macosx metalmust resolve). See Building from source. - There are no Linux or Windows builds — Metal is an Apple-only framework.
Capabilities
cairometal implements cairo's imaging model. The drawing primitives are executed on the GPU; surface I/O and geometry are handled on the CPU.
| Area | Supported |
|---|---|
| Surfaces | ImageSurface (ARGB32 / RGB24 / A8), recording surface, create_similar |
| Context state | save/restore stack, source color/pattern, line width/cap/join/dash, fill rule, operators |
| Paths | move_to, line_to, curve_to, rel_*, arc/arc_negative, rectangle, close_path, path copy/append |
| Painting | fill, stroke, paint, paint_with_alpha, clip (GPU stencil-then-cover) |
| Patterns | solid, LinearGradient, RadialGradient, surface patterns, mesh gradients |
| Groups | push_group / pop_group[_to_source] (off-screen layers composited on the GPU) |
| Compositing | Porter-Duff operators (over, in, out, atop, …) |
| Text | select_font_face, set_font_size, show_text, text_path, font/text extents (CoreText-backed) |
| Transforms | translate, scale, rotate, transform, full affine Matrix |
| Output | write_to_png, direct pixel access, IOSurface-backed buffers |
Names mirror pycairo. Porting existing pycairo code is usually just the import line; if a specific symbol is missing, please open an issue.
When the GPU helps (and when it doesn't)
GPU rasterization pays off for GPU-bound 2D work — large canvases, heavy compositing and layering, many primitives, repeated redraws. For light or typical cairo workloads (a small plot, a few shapes, one-off SVG/PDF), the CPU pycairo is just as fast and simpler — there's no benefit to the CPU↔GPU round-trip, and possibly a small cost. Reach for cairometal where rasterization is your bottleneck.
Migrating from pycairo
# before
import cairo
# after
import cairometal as cairo
The surface/context/pattern/matrix API and the FORMAT_* / OPERATOR_* / FONT_* constants are named as in pycairo. Differences to expect: macOS/arm64 only, text uses CoreText font lookup (so available faces match the system), and very new or rarely-used cairo entry points may not be implemented yet.
How it works (internals)
The installed package is small but wraps a real native engine:
cairometal/
__init__.py # sets $CM_METALLIB to the bundled lib, then re-exports the ext
cairo_metal.<abi>.so # the compiled Obj-C / Metal extension (~24 cm_* units)
default.metallib # the precompiled Metal shaders, shipped beside the .so
- The extension is compiled from the CPython glue
cairo_metal_ext.cplus the engine units: C sources (cm_matrix,cm_raster,cm_region,cm_pattern,cm_mesh,cm_state,cm_query,cm_font,cm_ft,cm_surface_format/similar) and Obj-C/Metal sources (cm_surface,cm_device,cm_path,cm_fill,cm_stroke,cm_paint,cm_clip,cm_group,cm_compose,cm_text,cm_recording,cm_surface_png). It is built with Obj-C ARC and links 11 Apple frameworks:Metal,MetalKit,QuartzCore,CoreVideo,IOSurface,Foundation,CoreFoundation,CoreText,CoreGraphics,ImageIO,UniformTypeIdentifiers. - Shaders (
shaders/*.metal) are compiled withxcrun -sdk macosx metal+metallibintodefault.metallib, shipped as package data. - Metallib discovery: at import,
__init__.pysets$CM_METALLIBto thedefault.metallibnext to the extension, so the engine loads it with zero configuration. The engine's lookup order is$CM_METALLIB→ the app/main-bundle default library → compile-from-source; you can override$CM_METALLIBto point at your own. - Why
import cairometalworks without a C edit: the extension is built as the submodulecairometal.cairo_metal, whose init symbol isPyInit_cairo_metal(named after the last path component) — exactly whatcairo_metal_ext.calready exports. So the same source serves both the desktop package and the iOS embedding (which imports a top-levelcairo_metal) with no source change. - Rendering approach: stencil-then-cover path filling, IOSurface-backed surfaces, GPU compositing for groups/clips.
- Antialiasing: the default is 4× MSAA.
ANTIALIAS_GOOD/ANTIALIAS_BEST(orCM_ANALYTIC_AA=1for every draw) use cairo-style measured coverage instead, which matches real cairo's edges much more closely at some GPU cost. - Batched frames: a surface's drawing is recorded into one GPU frame and rendered when the surface is flushed, read back or written out. A surface over your own page-aligned memory (
create_for_data) is drawn straight into that buffer. For such a surface, a frame whose draws all useOVERtouches only the pixels something was drawn on.
Building from source
# macOS + full Xcode (the Metal toolchain must be present)
git clone -b pip https://github.com/yu314-coder/cairometal
cd cairometal
pip install . # or: python -m build (wheel + sdist)
setup.py compiles the extension and the metallib. If the Metal toolchain isn't available it falls back to the committed prebuilt/default.metallib. To build a single-arch / pinned-deployment-target wheel:
MACOSX_DEPLOYMENT_TARGET=11.0 ARCHFLAGS="-arch arm64" python -m build --wheel
Wheels & releasing
- Wheels are tagged e.g.
cairometal-0.2.0-cp314-cp314-macosx_11_0_arm64.whl— per-CPython version, macOSarm64, deployment target 11.0. - Each release has a wheel for every CPython from 3.10 to 3.14, each tested in a fresh environment against the full test suite before upload.
- The repo also carries a cibuildwheel workflow (
.github/workflows/wheels.yml) that builds the same matrix on a macOS Apple-Silicon runner and publishes through PyPI Trusted Publishing (OIDC, no stored token) when av*tag is pushed. Trusted Publishing has to be set up on PyPI first. To add wheels to an already-published version, the publish step needsskip-existing: true.
Changes
0.2.0
- Wheels for CPython 3.10–3.14 (0.1.0 had a 3.14 wheel only).
- Closer to real cairo. Gradient fills and strokes had red and blue swapped, and a stroke gradient ignored the transform. Drawing after
flush()wiped what was drawn before it, and an empty flush blended the previous frame in again. Curves now flatten as cairo's do. - Measured antialiasing.
ANTIALIAS_GOOD/ANTIALIAS_BESTuse cairo-style coverage measured per pixel row, as cairo's own scan converter does. - No more hangs or out-of-memory errors. Drawing into four or more surfaces in turn, without flushing them, waited for ever for a GPU frame while holding the GIL. The oldest pending frame is now rendered early instead, with the same pixels. The registry that
_flush_allwalks now grows as needed (it stopped at 64 surfaces), and a frame wait that still finds no frame free raises an error after 20 s. A frame of about 1,800 or more draws no longer raises "out of memory". - Faster and lighter.
create_for_datadraws straight into a page-aligned caller buffer, and the GPU wrap over a numpy array is kept while the array lives. On such a surface, a frame ofOVERdraws touches only the pixels drawn on. Measured on manim frames at 4K: GPU wait went from 6.8–11.4 ms to 2.2–3.0 ms, and peak memory from 360–401 MB to 282–324 MB. - New
last_gpu_ms(): the GPU time of the last frame that was waited on.
0.1.0 — first release.
Origin
cairometal is the desktop release of a GPU cairo engine originally written for an iOS Python environment, where it provides a Metal-backed cairo for plotting/animation libraries. The same engine ships inside that app imported as a top-level cairo_metal; this package repackages it for macOS as import cairometal.
Limitations & notes
- Drawing is batched per surface. A surface's fills and strokes go into one GPU frame that is rendered when the surface is flushed (or read back, or written to PNG). Any number of surfaces may hold pending drawing: when the device's three frames are all open on other surfaces, the oldest is rendered early, which gives the same pixels cairo would.
- macOS / Apple Silicon only.
arm64wheels; thex86_64(Intel-Mac) path compiles but is currently untested. - Per-version wheels (not
abi3) — install the wheel matching your Python. - Independent re-implementation of a cairo-compatible API — not the cairo library or
pycairo. - Missing an entry point you need? Open an issue at the repo.
License
MIT © 2026 Yu Yao-Hsing — see LICENSE.
Metadata
Release files for cairometal 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cairometal-0.2.0.tar.gz | 441.0 kB | Without provenance | Details for cairometal-0.2.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| cairometal-0.2.0-cp314-cp314-macosx_11_0_arm64.whl | CPython 3.14 | CPython 3.14 | macOS 11.0+ ARM64 | Details for cairometal-0.2.0-cp314-cp314-macosx_11_0_arm64.whl |
| cairometal-0.2.0-cp313-cp313-macosx_11_0_arm64.whl | CPython 3.13 | CPython 3.13 | macOS 11.0+ ARM64 | Details for cairometal-0.2.0-cp313-cp313-macosx_11_0_arm64.whl |
| cairometal-0.2.0-cp312-cp312-macosx_11_0_arm64.whl | CPython 3.12 | CPython 3.12 | macOS 11.0+ ARM64 | Details for cairometal-0.2.0-cp312-cp312-macosx_11_0_arm64.whl |
| cairometal-0.2.0-cp311-cp311-macosx_11_0_arm64.whl | CPython 3.11 | CPython 3.11 | macOS 11.0+ ARM64 | Details for cairometal-0.2.0-cp311-cp311-macosx_11_0_arm64.whl |
| cairometal-0.2.0-cp310-cp310-macosx_11_0_arm64.whl | CPython 3.10 | CPython 3.10 | macOS 11.0+ ARM64 | Details for cairometal-0.2.0-cp310-cp310-macosx_11_0_arm64.whl |
Total release size: 1.6 MB
Release files / cairometal-0.2.0.tar.gz
| Download URL | cairometal-0.2.0.tar.gz |
|---|---|
| Size | 441.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e34d3462e97f40176f8cbbb79564acdb38b989a5f88715a451467a9be52d9406
|
|
BLAKE2b-256 checksum How to use checksums |
45181342a8bfb4040d602c7570a088200541928b74f014ca5cec2dad5fbe30c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cairometal-0.2.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | cairometal-0.2.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 224.2 kB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bb81fbf9ee11a811b1504a77e8688783223bcf0b7a2273ad78e1c1e132694702
|
|
BLAKE2b-256 checksum How to use checksums |
80b3b76bb45b810c0439e024a5e14e2f5b0ff0d456c3578c1b2c371c5a7f54be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cairometal-0.2.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | cairometal-0.2.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 224.2 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
902a112dfea813f6a46a8b10bf11d5e95dd4d6d41c41ebc8946c68277ee83793
|
|
BLAKE2b-256 checksum How to use checksums |
1a049b0037ceea3093fa6826fa30653d0175ac09fb35ad284e5d9e683c9608ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cairometal-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | cairometal-0.2.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 224.2 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5b7dcb259f2d953c1c614c4cf74933fdb173d03ea95288c9d9f0b91f1574ad5c
|
|
BLAKE2b-256 checksum How to use checksums |
b51ecd28d22fcefefd3bdd7814196665df70475cee9ecb4e793714c7b194f3c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cairometal-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | cairometal-0.2.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 225.1 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bcfc39304ef87f3461d387b4b1e215372328062095a02af25a9e2beb80b473aa
|
|
BLAKE2b-256 checksum How to use checksums |
899212ab5a059ded17d77a4e4b6077cc33d87996315305b1c5859d63314fe770
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cairometal-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | cairometal-0.2.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 225.1 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
13fe08273d7f32dfc83118a2f85cefa58cb876459daff404fe24cd2453b63fc9
|
|
BLAKE2b-256 checksum How to use checksums |
8bdde7dfaf40ff8f745d67233d3180217cc0e1f1e966f6ea3125fc5c2ebe28bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for cairometal 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.