Installing

WeasyPrint ‘v52.5’ depends on:

Python, cairo, Pango and GDK-PixBuf need to be installed separately. See platform-specific instructions for Linux, macOS and Windows below.

Install WeasyPrint with pip. This will automatically install most of dependencies. You probably need either a virtual environment (venv, recommended) or using sudo.

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.

You can also play with WeasyPrint Navigator or WeasyPrint Renderer. Start it with

python -m weasyprint.tools.navigator

or

python -m weasyprint.tools.renderer

and open your browser at http://127.0.0.1:5000/.

If everything goes well, you’re ready to start using WeasyPrint! Otherwise, please copy the full error message and report the problem.

1

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.

2

pango ≥ 1.29.3 is required, but 1.38.0 is needed to handle @font-face CSS rules.

3

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.

4

Without it, PNG and SVG are the only supported image formats. JPEG, GIF and others are not available.

Linux

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 libffi-dev.

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 1.

Fedora

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

Archlinux

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

Gentoo

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

Alpine

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

Note

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: /usr/local/lib/python3.7/site-packages/cairocffi/__init__.py

try:
    lib = ffi.dlopen(name)
    if lib:
...
cairo = dlopen(ffi, 'libcairo.so.2')

macOS

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

Windows

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 64 bit you can either use the GTK+ 64 Bit Installer or install the 64-bit GTK+ via MSYS2.

If your python architecture is 32 bit you’ll have to install the 32-bit GTK+ via MSYS2.

Note

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 Windows PATH.

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.cmd as described in the MSYS2 wiki.

  • Update the MSYS2 shell with

    pacman -Syuu

    Close the shell by clicking the close button in the upper right corner of the window.

  • Restart the MSYS2 shell. Repeat the command

    pacman -Su

    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:

    exit

  • Now that all the GTK files needed by WeasyPrint are in the .\mingw32 respectively in the .\mingw64 subfolder of your MSYS2 installation directory, we can (and must) make them accessible by injecting the appropriate folder into the PATH.

    Let’s assume you installed MSYS2 in C:\msys2. Then the folder to inject is:

    • C:\msys2\mingw32\bin for the 32 bit GTK+

    • C:\msys2\mingw64\bin for 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 PATH environment 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.

Note

Checking the option doesn’t insert the GTK-path at the beginning of your system 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 PATH.

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 PATH environment variable.

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:\msys2\mingw32\bin

  • C:\msys2\mingw64\bin

  • C:\Program Files\GTK3-Runtime Win64\bin

Determine the correct folder and execute the following commands, replace <path-to-recently-installed-gtk> accordingly:

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 PATH and 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.

Other Options for Installation

There is a .NET wrapper for WeasyPrint available here.