Here are some installation instructions for getting going. It is preferred to install from PyPi, however, you are welcome to build from source if you so desire.

Currently only Linux, Windows 64-bit and MacOS systems (Intel and ARM) are supported.

For all methods, if you want to use the included Loader class to load images, you will also need the MagickWand C-library. The installation of MagickWand is fairly straight forward.


For a substantial performance increase when importing Loader, you can set the MAGICK_HOME environment variable to where the ImageMagick library lives on your computer (i.e. for brew users, something like /usr/local/Cellar/imagemagick/).

From PyPi is available on PyPi. You can install it by running

pip install

If you are using MacOS, make sure to set your MAGICK_HOME environment variable appropriately or the Loader might not find the ImageMagick.

From source

When building from source, make sure you have installed the following:

  • Chafa, specifically that you have libchafa somewhere on your path

  • Hatchling

  • glib-2.0

To install from source, clone repository and run

hatchling build -t wheel

When the build is finished (you might see some warnings, they are safe to ignore), there should be a .whl file in a new dist/ folder. To install that, run

pip install dist/{filename}.whl

replacing {filename} with the appropriate file name.


When installing from source, you have to make sure libchafa and libglib-2.0 are somewhere on your path so can find and use them.