# Installing¶

WeasyPrint 52.1 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¶

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

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

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

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