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:
macOS Windows Linux
Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies:
brew install cairo freetype libffi libjpeg libpng zlib
The easiest way to get up and running with the Cairo Graphics library is by installing it via MSYS2, which is a software distribution and building platform for Windows. Run the following command inside of a MSYS2 shell:
pacman -S mingw-w64-ucrt-x86_64-cairo
MSYS2 provides the Cairo Graphics library in several different environments. The above command uses the UCRT64 environment, as recommended by the MSYS2 developers.
There are several package managers for Linux with varying availability per distribution. The installation guide explains how to install the Cairo Graphics library for your distribution:
Ubuntu Fedora openSUSE
apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
The following environments come with a preinstalled version of Cairo Graphics:
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:
macOS Windows Linux
Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies:
The easiest way to get pngquant is by installing it via MSYS2, which is a software distribution and building platform for Windows. Run the following command inside of a MSYS2 shell:
pacman -S mingw-w64-ucrt-x86_64-pngquant
All popular Linux distributions, regardless of package manager, should allow to install pngquant with the bundled package manager. For example, on Ubuntu, pngquant can be installed with:
The same is true for yum and zypper.
The following environments come with a preinstalled version of pngquant:
After following the installation guide above it may happen that you still get the following error:
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.
macOS Windows Linux
On macOS the library lookup checks inside paths defined in dyld. Additionally each library name is checked in three variants with the libname.dylib, name.dylib and name.framework/name format.
Homebrew should set every needed variable to point at the installed library directory, but if that didn't happen, you can use the debug script below to see what paths are looked up.
A known workaround is to add the Homebrew lib path directly before running MkDocs:
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
View source code of cairo-lookup-macos.py
Python Debug macOS Scriptcurl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py" | python -
On Windows the library lookup checks inside the paths defined in the environmental PATH variable. Additionally each library name is checked in two variants with the name and name.dll format.
The default binary and shared library path for the UCRT64 environment of MSYS2, in which the packages were installed using the above commands, is:
Use the debug script below to check if the path is included. If it isn't then:
SystemPropertiesAdvanced applet.Path variable.$env:Path -split ';'
View source code of cairo-lookup-windows.py
PowerShell - Python Debug Windows Script(Invoke-WebRequest "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py").Content | python -
On Linux the library lookup can differ greatly and is dependent from the installed distribution. For tested Ubuntu and Manjaro systems Python runs shell commands to check which libraries are available in ldconfig, in the gcc/cc compiler, and in ld.
You can extend the LD_LIBRARY_PATH environmental variable with an absolute path to a library directory containing libcairo.so etc. Run this directly before MkDocs:
export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH
You can also modify the /etc/ld.so.conf file.
The Python script below shows, which function is being run to find installed libraries. You can check the source to find out what specific commands are executed on your system during library lookup.
View source code of cairo-lookup-linux.py
Python Debug Linux Scriptcurl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4