Introduction to generativepy

By Martin McBride, 2026-08-20

Categories: generativepy


generativepy is an open-source Python drawing library for creating computer images, diagrams, and animations. It can be found on github. This article covers generativepy V50.00, although much of it will also apply to older or newer versions.

About generativepy

As mentioned above, generativepy is a Python library for creating images, diagrams, animations, and videos. It is general purpose but includes features that make it particularly suitable for creating mathematical and technical diagrams and videos.

generativepy is a library. It has no user interface. To create a diagram or video, you need to write some Python code that calls the library. This guide gives lots of examples, and the code to create a simple diagram isn't complicated. Of course, if you want to create a very complex diagram, the code can get as sophisticated as you like.

Uses

generativepy can create images and animations (movies and GIFs). It is particularly suitable for geometry diagrams, graphs, and other mathematical illustrations, but it can handle any diagram that can be built from drawing primitives.

Because diagrams are created programmatically, it is especially useful when you need to update diagrams frequently with new data, since changes can be made automatically without manual effort each time.

Installing

generativepy is a pure Python library. It is available on the Python Package Index (https://pypi.org/project/generativepy/), so you can install it with pip, uv, or your favourite package manager. Or it can just be downloaded from github (https://github.com/martinmcbride/generativepy) and placed in a suitable location.

It has the following Python library requirements:

  • numpy 2.5.2
  • pycairo 1.29.1
  • pillow 11.3.0 (moviepy might not be compatible with pillow 12.x)
  • moviepy 2.2.1

It also requires the following command-line utilities to be installed:

  • LaTeX TeXLive 2023
  • dvipng 1.15
  • gifsicle 1.94
  • ffmpeg 6.1.1

History

generativepy started as a wrapper for the Pycairo graphics library. At the time, I wanted to experiment with generative art. However, I was also building the GraphicMaths website, and I quickly realised the library could also be useful for creating mathematical diagrams for the site. Over the years, I have continued developing the library while also using it to create images and videos.

So far I have created diagrams for a couple of hundred online maths articles and several maths books. I have also created about 100 YouTube videos using the library's video capabilities.

While I developed the library primarily for my own use, it has always been available as an open-source library, and I have done my best to make it useful for others. I have reorganised the code a few times to keep the interfaces consistent, but at this stage the library is mature and stable, and most docstrings are up to date.

Together with this guide, anyone who is a reasonably capable Python coder should be able to use generativepy to create images and animations.

Features

generativepy has the following features:

  • Vector drawing - generativepy uses the Pycairo library, which is a very capable, high-quality vector graphics library supporting geometric shapes, text, different fill and stroke styles, coordinate transformations, transparency, and clipping. It has most of the features of a vector graphics program such as Inkscape, but is controlled by Python code. You can save images as PNG or SVG files.
  • Bitmap drawing - bitmap images can be created or manipulated using the Pillow library, a well-known Python imaging library. You can also convert images to NumPy arrays and manipulate them using NumPy and related libraries (for example, SciPy). Bitmap images can be saved as PNG files.
  • Color - generativepy supports grayscale and RGB colour, with optional transparency. The colour library lets you create colours from RGB values, HSL values, or CSS colour names, and lets you create new colours by manipulating existing ones in various ways.
  • Compositing - all images are accessible as frames. A frame is a NumPy array. This lets you combine two images any way you want before saving them as an image or animation frame (see next).
  • Animation - generativepy can be used to create a sequence of frames for animation. You can store these as animated GIFs, mp4 files, or a sequence of PNG images to process in an external video editor. Individual frames are stored in the standard frame format (NumPy arrays) so frames can be processed/combined while the video is being created (eg for text overlay, picture-in-picture, or other effects). There is a simple tweening system for animation. You can add audio as the video is created.
  • Maths features - generativepy supports various features for geometric diagrams, including angle markers, tick marks, etc. It can plot graphs, add annotations, and also create tables. You can mix these with other drawings on the same image. It can render LaTeX formulas and place them on the same image. All maths features can be animated, just like any other drawing features.

genpygoodies

genpygoodies is an additional library you can use alongside generativepy. It adds extra functionality that is either more specialised or less well-defined. It is a place where I add things that may or may not be useful, so they haven't quite earned their place in the main library.

This library might be slightly less stable than the main library, as some features might evolve.

Related articles