Gizeh is a Python library for vector graphics, built on top of cairocffi (Cairo bindings for Python). Cairo is powerful but low-level; Gizeh adds a small set of intuitive primitives to make drawing easier.

# Let's draw a red circle! import gizeh surface = gizeh.Surface(width=320, height=260) # pixels circle = gizeh.circle(r=30, xy=[40, 40], fill=(1, 0, 0)) circle.draw(surface) # draw the circle on the surface surface.write_to_png("circle.png") # export as PNG

See Gizeh in action (combined with MoviePy for animations) in this blog post.

Gizeh supports Python 3.7+.

Gizeh requires the Cairo graphics library to be installed on your system.

• macOS (Homebrew):
  • brew install cairo pkg-config
• Debian/Ubuntu:
  • sudo apt-get install -y libcairo2-dev pkg-config

Then install the Python package:

pip install gizeh

Alternatively, from source (editable/development install):

pip install -e .

This guide, along with the examples in gizeh/examples, should give you everything you need to get started. Check docstrings for details.

A Surface is a rectangle of fixed dimensions (in pixels) on which you draw elements, and which you can save/export as an image:

import gizeh # initialize surface surface = gizeh.Surface(width=320, height=260) # in pixels # make a shape and draw it on the surface circle = gizeh.circle(r=30, xy=[40, 40], fill=(1, 1, 1)) circle.draw(surface) # export the surface surface.get_npimage() # returns a (width x height x 3) numpy array surface.write_to_png("circle.png")

Basic elements are circles, rectangles, lines, text, etc., that you draw on a surface using my_element.draw(surface). Common parameters:

• xy: center coordinates of the object. At render time (surface.write_to_png) you can set y_origin to "top" (default) or "bottom". With "top", (0, 0) is the upper-left of the final image; the bottom-right is (width, height). With "bottom", (0, 0) is the bottom-left (like plots), and (width, height) is the top-right.
• angle: rotation (radians) around xy.
• fill: interior fill (default: none). Can be a color (R, G, B), gradient, image pattern, etc.
• stroke: contour fill; same rules as fill.
• stroke_width: contour width (pixels). Default is 0 (no stroke).

Examples:

import numpy as np Pi = np.pi circ = gizeh.circle(r=30, xy=(50, 50), fill=(1, 1, 1)) rect = gizeh.rectangle(lx=60.3, ly=45, xy=(60, 70), fill=(0, 1, 0), angle=Pi/8) sqr = gizeh.square(l=20, stroke=(1, 1, 1), stroke_width=1.5) arc = gizeh.arc(r=20, a1=Pi/4, a2=3*Pi/4, fill=(1, 1, 1)) text = gizeh.text("Hello world", fontfamily="Impact", fontsize=40, fill=(1, 1, 1), xy=(100, 100), angle=Pi/12) poly = gizeh.regular_polygon(r=40, n=5, angle=np.pi/4, xy=[40, 50], fill=(1, 0, 1)) line = gizeh.polyline(points=[(0, 0), (20, 30), (40, 40), (0, 10)], stroke_width=3, stroke=(1, 0, 0), fill=(0, 1, 0))

fill and stroke can be:

• RGB (r, g, b) with values in [0, 1]
• RGBA (r, g, b, a) with a in [0, 1]
• gizeh.ColorGradient
• gizeh.ImagePattern (an image)
• A NumPy RGB/RGBA image array (where implemented)

Elements can be transformed (translated, rotated, scaled). All transformations are out-of-place: they return a modified copy.

square_1 = gizeh.square(l=20, xy=[30, 35], fill=(1, 0, 0)) square_2 = square_1.rotate(np.pi/8) # rotation around [0, 0] by default square_3 = square_2.rotate(np.pi/4, center=[10, 15]) # rotation around a center square_4 = square_1.scale(2) # two times bigger square_5 = square_1.scale(sx=2, sy=3) # width x2, height x3 square_6 = square_1.scale(2, center=[30, 30]) # zoom around a center square_7 = square_1.translate(xy=[5, 15]) # translation

A Group is a collection of elements (including nested groups) transformed and drawn together:

square = gizeh.square(l=20, fill=(1, 0, 0), xy=(40, 40)) circle = gizeh.circle(r=20, fill=(1, 1, 0), xy=(50, 30)) group_1 = gizeh.Group([square, circle]) group_2 = group_1.translate(xy=[30, 30]).rotate(np.pi/4) group_3 = gizeh.Group([circle, group_1]) surface = gizeh.Surface(width=300, height=200) group_1.draw(surface) group_2.draw(surface) group_3.draw(surface) surface.write_to_png("my_masterwork.png")

If pip installation fails, ensure you have the system Cairo development packages and pkg-config installed (see “Installation” above).

• macOS (Homebrew): brew install cairo pkg-config
• Debian/Ubuntu: sudo apt-get install -y libcairo2-dev pkg-config

Development uses uv for fast Python packaging and workflows.

Prerequisites:

• Install system packages
  • macOS: brew install uv cairo pkg-config
  • Debian/Ubuntu: sudo apt-get install -y libcairo2-dev pkg-config and install uv from its docs

Setup and install deps:

uv python install 3.12 uv venv --python 3.12 uv sync --group dev

Run tests:

uv run pytest -q

Run a specific test:

uv run pytest -q tests/test_samples.py::test_random_squares

Quick import check:

uv run python -c "import gizeh, numpy, cairocffi; print('ok')"

Install and run pre-commit hooks:

uv run pre-commit install uv run pre-commit run --all-files

Gizeh is open-source (MIT) by Zulko. Contributions are welcome—issues and pull requests on GitHub.