WeasyPrint 52.2 depends on:
- CPython ≥ 3.6.0
- cairo ≥ 1.15.4 
- Pango ≥ 1.38.0 
- setuptools ≥ 30.3.0 
- CFFI ≥ 0.6
- html5lib ≥ 0.999999999
- cairocffi ≥ 0.9.0
- tinycss2 ≥ 1.0.0
- cssselect2 ≥ 0.1
- CairoSVG ≥ 2.4.0
- Pyphen ≥ 0.9.1
- Pillow ≥ 4.0.0
- GDK-PixBuf ≥ 2.25.0 
Install WeasyPrint with pip. This will automatically install most of
dependencies. You probably need either a virtual environment (venv,
recommended) or using
python3 -m venv ./venv . ./venv/bin/activate pip install WeasyPrint
Now let’s try it:
weasyprint --help weasyprint http://weasyprint.org ./weasyprint-website.pdf
You should see warnings about unsupported CSS 3 stuff; this is expected. In the PDF you should see the WeasyPrint logo on the first page.
python -m weasyprint.tools.navigator
python -m weasyprint.tools.renderer
and open your browser at http://127.0.0.1:5000/.
|||cairo ≥ 1.15.4 is best but older versions may work too. The test suite passes on cairo 1.14, and passes with some tests marked as “expected failures” on 1.10 and 1.12 due to behavior changes or bugs in cairo. If you get incomplete SVG renderings, please read #339. If you get invalid PDF files, please read #565. Some PDF metadata including PDF information, hyperlinks and bookmarks require 1.15.4.|
|||pango ≥ 1.29.3 is required, but 1.38.0 is needed to handle @font-face CSS rules.|
|||setuptools ≥ 30.3.0 is required to install WeasyPrint from wheel, but 39.2.0 is required to build the package or install from source. setuptools < 40.8.0 will not include the LICENSE file.|
|||Without it, PNG and SVG are the only supported image formats. JPEG, GIF and others are not available.|
Pango, GdkPixbuf, and cairo can not be installed
with pip and need to be installed from your platform’s packages.
CFFI can, but you’d still need their own dependencies.
This section lists system packages for CFFI when available,
the dependencies otherwise.
CFFI needs libffi with development files. On Debian, the package is called
If your favorite system is not listed here but you know the package names, tell us so we can add it here.
Debian / Ubuntu¶
WeasyPrint is packaged for Debian 11 or newer.
You can install it with pip on Debian 10 Buster or newer, or on Ubuntu 18.04 Bionic Beaver or newer, after installing the following packages:
sudo apt-get install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
WeasyPrint may work under previous releases of Debian or Ubuntu, but they often provide an old version of Cairo that may limit WeasyPrint’s features .
WeasyPrint is packaged for Fedora, but you can install it with pip after installing the following packages:
sudo yum install redhat-rpm-config python-devel python-pip python-setuptools python-wheel python-cffi libffi-devel cairo pango gdk-pixbuf2
WeasyPrint is available in the AUR, but you can install it with pip after installing the following packages:
sudo pacman -S python-pip python-setuptools python-wheel cairo pango gdk-pixbuf2 libffi pkg-config
WeasyPrint is packaged in Gentoo, but you can install it with pip after installing the following packages:
emerge pip setuptools wheel cairo pango gdk-pixbuf cffi
For Alpine Linux 3.6 or newer:
apk --update --upgrade add gcc musl-dev jpeg-dev zlib-dev libffi-dev cairo-dev pango-dev gdk-pixbuf-dev
Some Alpine images do not resolv the library path via ctypes.utils.find_library. So if you get
OSError: dlopen() failed to load a library: cairo / cairo-2 / cairo-gobject-2
then change find_library and open the library directly:
try: lib = ffi.dlopen(name) if lib: ... cairo = dlopen(ffi, 'libcairo.so.2')
WeasyPrint is automatically installed and tested on virtual macOS machines. The official installation method relies on Homebrew. Install Homebrew if you haven’t already:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install Python, cairo, Pango and GDK-PixBuf using Homebrew:
brew install python3 cairo pango gdk-pixbuf libffi
Don’t forget to use the pip3 command to install WeasyPrint, as pip may be using the version of Python installed with macOS:
pip3 install WeasyPrint
If you get the Fontconfig error: Cannot load default config file message, then try reinstalling fontconfig:
brew uninstall fontconfig brew install fontconfig
You can also try with Macports, but please notice that this solution is not tested and thus not recommended (also known as “you’re on your own and may end up crying blood with sad dolphins for eternity”):
sudo port install py-pip cairo pango gdk-pixbuf2 libffi
Dear Windows user, please follow these steps carefully.
Really carefully. Don’t cheat.
Besides a proper Python installation and a few Python packages, WeasyPrint needs the Pango, cairo and GDK-PixBuf libraries. They are required for the graphical stuff: Text and image rendering. These libraries aren’t Python packages. They are part of GTK+ (formerly known as GIMP Toolkit), and must be installed separately.
The following installation instructions for the GTK+ libraries don’t work on Windows XP. That means: Windows Vista or later is required.
Of course you can decide to install ancient WeasyPrint versions with an erstwhile Python versions, combine it with outdated GTK+ libraries on any Windows version you like, but if you decide to do that you’re on your own, don’t even try to report an issue, kittens will die because of you.
Step 1 - Install Python¶
Install the latest Python 3.x
- On Windows 32 bit download the “Windows x86 executable installer”
- On Windows 64 bit download the “Windows x86-64 executable installer”
Follow the instructions. You may customize your installation as you like, but we suggest that you “Add Python 3.x to PATH” for convenience and let the installer “install pip”.
Step 2 - Update pip and setuptools packages¶
Python is bundled with modules that may have been updated since the release. Please open a Command Prompt and execute the following command:
python -m pip install --upgrade pip setuptools
Step 3 - Install WeasyPrint¶
In the console window execute the following command to install the WeasyPrint package:
python -m pip install WeasyPrint
Step 4 - Install the GTK+ libraries¶
There’s one thing you must observe:
- If your Python is 32 bit you must use the 32 bit versions of those libraries.
- If your Python is 64 bit you must use the 64 bit versions of those libraries.
If you mismatch the bitness, the warning about kittens dying applies.
In case you forgot which Python architecture you installed, you can find out by running the following command in command prompt:
python --version --version
If your python architecture is 32 bit you’ll have to install the 32-bit GTK+ via MSYS2.
Installing those libraries doesn’t mean something extraordinary. It only
means that the files must be on your computer and WeasyPrint must be able
to find them, which is achieved by putting the path-to-the-libs into your
Install GTK+ with the aid of MSYS2¶
Sadly the GTK+ Runtime for 32 bit Windows was discontinued in April 2017. Since then developers are advised to either bundle GTK+ with their software (which is beyond the capacities of the WeasyPrint maintainers) or install it through the MSYS2 project.
With the help of MSYS2, both the 32 bit as well as the 64 bit GTK+ can be installed. If you installed the 64 bit Python and don’t want to bother with MSYS2, then go ahead and use the GTK+ 64 Bit Installer.
MSYS2 is a development environment. We (somehow) mis-use it to only supply the
up-to-date GTK+ runtime library files in a subfolder we can inject into our
PATH. But maybe you get interested in the full powers of MSYS2. It’s the
perfect tool for experimenting with MinGW and cross-platform development – look
at its wiki.
Ok, let’s install GTK3+.
Download and run the MSYS2 installer
- On 32 bit Windows: “msys2-i686-xxxxxxxx.exe”
- On 64 bit Windows: “msys2-x86_64-xxxxxxxx.exe”
You alternatively may download a zipped archive, unpack it and run
msys2_shell.cmdas described in the MSYS2 wiki.
Update the MSYS2 shell with
Close the shell by clicking the close button in the upper right corner of the window.
Restart the MSYS2 shell. Repeat the command
until it says that there are no more packages to update.
Install the GTK+ package and its dependencies.
To install the 32 bit (i686) GTK run the following command:
pacman -S mingw-w64-i686-gtk3
The command for the 64 bit (x86_64) version is:
pacman -S mingw-w64-x86_64-gtk3
The x86_64 package cannot be installed in the 32 bit MSYS2!
Close the shell:
Now that all the GTK files needed by WeasyPrint are in the
.\mingw32respectively in the
.\mingw64subfolder of your MSYS2 installation directory, we can (and must) make them accessible by injecting the appropriate folder into the
Let’s assume you installed MSYS2 in
C:\msys2. Then the folder to inject is:
C:\msys2\mingw32\binfor the 32 bit GTK+
C:\msys2\mingw64\binfor the 64 bit GTK+
You can either persist it through Advanced System Settings – if you don’t know how to do that, read How to set the path and environment variables in Windows – or temporarily inject the folder before you run WeasyPrint.
GTK+ 64 Bit Installer¶
If your Python is 64 bit you can use an installer extracted from MSYS2 and provided by Tom Schoonjans.
- Download and run the latest gtk3-runtime-x.x.x-x-x-x-ts-win64.exe
- If you prefer to manage your
PATHenvironment varaiable yourself you should uncheck “Set up PATH environment variable to include GTK+” and supply it later – either persist it through Advanced System Settings or temporarily inject it before you run WeasyPrint.
Checking the option doesn’t insert the GTK-path at the beginning of your
PATH, but rather appends it. If there is already another
(outdated) GTK on your
PATH this will lead to unpleasant problems.
In any case: When executing WeasyPrint the GTK libraries must be on its
Step 5 - Run WeasyPrint¶
Now that everything is in place you can test WeasyPrint.
Open a fresh Command Prompt and execute
python -m weasyprint http://weasyprint.org weasyprint.pdf
If you get an error like
OSError: dlopen() failed to load a library: cairo /
cairo-2 it’s probably because cairo (or another GTK+ library mentioned in the
error message) is not properly available in the folders listed in your
Since you didn’t cheat and followed the instructions the up-to-date and complete set of GTK libraries must be present and the error is an error.
Let’s find out. Enter the following command:
WHERE libcairo-2.dll WHERE zlib1.dll
This should respond with path\to\recently\installed\gtk\binaries\libcairo-2.dll, for example:
C:\msys2\mingw64\bin\libcairo-2.dll C:\Program Files\GTK3-Runtime Win64\bin\zlib1.dll
If your system answers with nothing found or returns a filename not related to your recently-installed-gtk or lists more than one location and the first file in the list isn’t actually in a subfolder of your recently-installed-gtk, then we have caught the culprit.
Depending on the GTK installation route you took, the proper folder name is something along the lines of:
C:\Program Files\GTK3-Runtime Win64\bin
Determine the correct folder and execute the following commands, replace
SET PROPER_GTK_FOLDER=<path-to-recently-installed-gtk> SET PATH=%PROPER_GTK_FOLDER%;%PATH%
This puts the appropriate GTK at the beginning of your
its files are the first found when WeasyPrint requires them.
Call WeasyPrint again:
python -m weasyprint http://weasyprint.org weasyprint.pdf
If the error is gone you should either fix your
PATH permanently (via
Advanced System Settings) or execute the above
SET PATH command by
default (once!) before you start using WeasyPrint.
If the error still occurs and if you really didn’t cheat then you are allowed to open a new issue. You can also find extra help in this bug report. If you cheated, then, you know: Kittens already died.