Image processing

Image processing

Some of the built-in plugins depend on external libraries for efficient image processing, most notably the social plugin to generate social cards, and the optimize plugin for applying image optimization. This guide explains how to install those libraries in different environments.

Dependencies

The libraries for image processing are entirely optional, and only need to be installed if you want to use the social plugin or the optimize plugin. The libraries are listed under the imaging extra: 

pip install "mkdocs-material[imaging]"

This will install compatible versions of the following packages:

Cairo Graphics

Cairo Graphics is a graphics library and dependency of Pillow, which Material for MkDocs makes use of for generating social cards and performing image optimization. See the following section which explains how to install Cairo Graphics and its dependencies on your system:

The following environments come with a preinstalled version of Cairo Graphics:

pngquant

pngquant is an excellent library for lossy PNG compression, and a direct dependency of the built-in optimize plugin. See the following section which explains how to install pngquant system:

The following environments come with a preinstalled version of pngquant:

Troubleshooting

Cairo library was not found

After following the installation guide above it may happen that you still get the following error:

bash 
no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found
cannot load library 'libcairo.so.2': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
cannot load library 'libcairo.2.dylib': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
cannot load library 'libcairo-2.dll': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'

This means that the cairosvg package was installed, but the underlying cairocffi dependency couldn’t find the installed library. Depending on the operating system the library lookup process is different:

Tip

Before proceeding remember to fully restart any open Terminal windows, and their parent hosts like IDEs to reload any environmental variables, which were altered during the installation process. This might be the quick fix.