First Steps

Installation

WeasyPrint ‘stable’ depends on:

There are many ways to install WeasyPrint, depending on the system you use.

Linux

The easiest way to install WeasyPrint on Linux is to use the package manager of your distribution. WeasyPrint is packaged for recent versions of Debian, Ubuntu, Fedora, Archlinux, Gentoo

If WeasyPrint is not available on your distribution, or if you want to use a more recent version of WeasyPrint, you have to be sure that Python (at least version 3.6.0) and Pango (at least version 1.44.0) are installed on your system. You can verify this by launching:

python3 --version
pango-view --version

If the version of Pango provided by your distribution is too old, you can use version 52.5 of WeasyPrint which does not need recent Pango features.

When everything is OK, you can install WeasyPrint directly on your system or in a virtual environment using pip:

python3 -m venv venv
source venv/bin/activate
pip install weasyprint
weasyprint --info

Alpine ≥ 3.12

To install WeasyPrint without a virtualenv, you need the following packages:

apk add py3-pip py3-pillow py3-cffi py3-brotli gcc musl-dev python3-dev pango

To install WeasyPrint inside a virtualenv using wheels (if possible), you need the following packages:

apk add py3-pip gcc musl-dev python3-dev pango zlib-dev jpeg-dev openjpeg-dev g++ libffi-dev

To install WeasyPrint inside a virtualenv without using wheels, you need the following packages:

apk add py3-pip gcc musl-dev python3-dev pango zlib-dev jpeg-dev openjpeg-dev g++ libffi-dev

Archlinux

To install WeasyPrint without a virtualenv, you need the following packages:

pacman -S python-pip pango python-cffi python-pillow python-brotli python-zopfli

To install WeasyPrint inside a virtualenv using wheels (if possible), you need the following packages:

pacman -S python-pip pango

To install WeasyPrint inside a virtualenv without using wheels, you need the following packages:

pacman -S python-pip pango gcc libjpeg-turbo openjpeg2

Debian ≥ 11

To install WeasyPrint without a virtualenv, you need the following packages:

apt install python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0

To install WeasyPrint inside a virtualenv using wheels (if possible), you need the following packages:

apt install python3-pip libpango-1.0-0 libpangoft2-1.0-0

To install WeasyPrint inside a virtualenv without using wheels, you need the following packages:

apt install python3-pip libpango-1.0-0 libpangoft2-1.0-0 libjpeg-dev libopenjp2-7-dev libffi-dev

Fedora ≥ 34

To install WeasyPrint without a virtualenv, you need the following packages:

yum install python-pip python-pillow python-cffi python3-brotli pango

To install WeasyPrint inside a virtualenv using wheels (if possible), you need the following packages:

yum install python-pip pango

To install WeasyPrint inside a virtualenv without using wheels, you need the following packages:

yum install python-pip pango gcc python3-devel gcc-c++ zlib-devel libjpeg-devel openjpeg2-devel libffi-devel

Ubuntu ≥ 20.04

To install WeasyPrint without a virtualenv, you need the following packages:

apt install python3-pip python3-cffi python3-brotli libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

To install WeasyPrint inside a virtualenv using wheels (if possible), you need the following packages:

apt install python3-pip libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

To install WeasyPrint inside a virtualenv without using wheels, you need the following packages:

apt install python3-pip libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libffi-dev libjpeg-dev libopenjp2-7-dev

macOS

The easiest way to install WeasyPrint on macOS is to use Homebrew.

When Homebrew is installed, install Python, Pango and libffi:

brew install python pango libffi

You can then install WeasyPrint in a virtual environment using pip:

python3 -m venv venv
source venv/bin/activate
pip install weasyprint
weasyprint --info

Windows

Installing WeasyPrint on Windows requires to follow a few steps that may not be easy. Please read this chapter carefully.

Only Windows 10 64-bit is supported. You can find this information in the Control Panel → System and Security → System.

The first step is to install the latest version of Python from the Microsoft Store.

When Python is installed, you have to install GTK. Download the latest GTK3 installer and launch it. If you don’t know what some options mean, you can safely keep the default options selected.

When everything is OK, you can launch a command prompt by clicking on the Start menu, typing “cmd” and clicking the “Command Prompt” icon. You can then install WeasyPrint in a virtual environment using pip:

python3 -m venv venv
venv\Scripts\activate.bat
python3 -m pip install weasyprint
python3 -m weasyprint --info

Other Solutions

Other solutions are available to install WeasyPrint. These solutions are not tested but they are known to work for some use cases on specific platforms.

Macports

On macOS, you can install WeasyPrint’s dependencies with Macports:

sudo port install py-pip pango libffi

You can then install WeasyPrint in a virtual environment using pip:

python3 -m venv venv
source venv/bin/activate
pip install weasyprint
weasyprint --info

Conda

On Linux and macOS, WeasyPrint is available on Conda, with a WeasyPrint package on Conda Forge.

WSL

On Windows, you can also use WSL and install WeasyPrint the same way it has to be installed on Linux.

.NET Wrapper

On Windows, Bader Albarrak maintains a .NET wrapper.

AWS

Kotify maintains an AWS Lambda layer, see issue #1003 for more information.

Troubleshooting

Most of the installation problems have already been met, and some issues on GitHub could help you to solve them.

Missing Library

On Windows, most of the problems come from unreachable libraries. If you get an error like cannot load library 'xxx': error xxx, it means that this library is not installed or not in the PATH environment variable.

You can find more about this issue in #589, #721 or #1240.

Missing Fonts

If no character is drawn in the generated PDF, or if you get squares instead of letters, you have to install fonts and make them available to WeasyPrint. Following the standard way to install fonts on your system should be enough. You can also use @font-face rules to explicitly reference fonts using URLs.

Command-Line

Using the WeasyPrint command line interface can be as simple as this:

weasyprint http://weasyprint.org /tmp/weasyprint-website.pdf

You may see warnings on the standard error output about unsupported CSS properties. See Command-line API for the details of all available options.

In particular, the -s option can add a filename for a user stylesheet. For quick experimentation however, you may not want to create a file. In bash or zsh, you can use the shell’s redirection instead:

weasyprint http://weasyprint.org /tmp/weasyprint-website.pdf \
    -s <(echo 'body { font-family: serif !important }')

If you have many documents to convert you may prefer using the Python API in long-lived processes to avoid paying the start-up costs every time.

Python Library

Attention

Using WeasyPrint with untrusted HTML or untrusted CSS may lead to various security problems.

Quickstart

The Python version of the above example goes like this:

from weasyprint import HTML
HTML('http://weasyprint.org/').write_pdf('/tmp/weasyprint-website.pdf')

… or with the inline stylesheet:

from weasyprint import HTML, CSS
HTML('http://weasyprint.org/').write_pdf('/tmp/weasyprint-website.pdf',
    stylesheets=[CSS(string='body { font-family: serif !important }')])

Instantiating HTML and CSS Objects

If you have a file name, an absolute URL or a readable file object, you can just pass it to HTML or CSS to create an instance. Alternatively, use a named argument so that no guessing is involved:

from weasyprint import HTML

HTML('../foo.html')  # Same as …
HTML(filename='../foo.html')

HTML('http://weasyprint.org')  # Same as …
HTML(url='http://weasyprint.org')

HTML(sys.stdin)  # Same as …
HTML(file_obj=sys.stdin)

If you have a byte string or Unicode string already in memory you can also pass that, although the argument must be named:

from weasyprint import HTML, CSS

# HTML('<h1>foo') would be filename
HTML(string='''
    <h1>The title</h1>
    <p>Content goes here
''')
CSS(string='@page { size: A3; margin: 1cm }')

If you have @font-face rules in your CSS, you have to create a FontConfiguration object:

from weasyprint import HTML, CSS
from weasyprint.text.fonts import FontConfiguration

font_config = FontConfiguration()
html = HTML(string='<h1>The title</h1>')
css = CSS(string='''
    @font-face {
        font-family: Gentium;
        src: url(http://example.com/fonts/Gentium.otf);
    }
    h1 { font-family: Gentium }''', font_config=font_config)
html.write_pdf(
    '/tmp/example.pdf', stylesheets=[css],
    font_config=font_config)

Rendering to a Single File

Once you have a HTML object, call its HTML.write_pdf() method to get the rendered document in a single PDF file.

Without arguments, this method returns a byte string in memory. If you pass a file name or a writable file object, they will write there directly instead. (Warning: with a filename, these methods will overwrite existing files silently.)

Individual Pages & Meta-Data

If you want more than a single PDF, the HTML.render() method gives you a document.Document object with access to individual document.Page objects. Thus you can get the number of pages, their size1, the details of hyperlinks and bookmarks, etc. Documents also have a document.Document.write_pdf() method, and you can get a subset of the pages with document.Document.copy(). Finally, for ultimate control, document.Page.paint() individual pages anywhere on any pydyf.Stream.

1

Pages in the same document do not always have the same size.

See the Python API for details. A few random examples:

# Write odd and even pages separately:
#   Lists count from 0 but page numbers usually from 1
#   [::2] is a slice of even list indexes but odd-numbered pages.
document.copy(document.pages[::2]).write_pdf('odd_pages.pdf')
document.copy(document.pages[1::2]).write_pdf('even_pages.pdf')
# Print the outline of the document.
# Output on http://www.w3.org/TR/CSS21/intro.html
#     1. Introduction to CSS 2.1 (page 2)
#       1. A brief CSS 2.1 tutorial for HTML (page 2)
#       2. A brief CSS 2.1 tutorial for XML (page 5)
#       3. The CSS 2.1 processing model (page 6)
#         1. The canvas (page 7)
#         2. CSS 2.1 addressing model (page 7)
#       4. CSS design principles (page 8)
def print_outline(bookmarks, indent=0):
    for i, bookmark in enumerate(bookmarks, 1):
        page = bookmark.destination[0]
        print('%s%d. %s (page %d)' % (
            ' ' * indent, i, bookmark.label.lstrip('0123456789. '), page))
        print_outline(bookmark.children, indent + 2)
print_outline(document.make_bookmark_tree())

URL Fetchers

WeasyPrint goes through a URL fetcher to fetch external resources such as images or CSS stylesheets. The default fetcher can natively open file and HTTP URLs, but the HTTP client does not support advanced features like cookies or authentication. This can be worked-around by passing a custom url_fetcher callable to the HTML or CSS classes. It must have the same signature as default_url_fetcher().

Custom fetchers can choose to handle some URLs and defer others to the default fetcher:

from weasyprint import default_url_fetcher, HTML

def my_fetcher(url):
    if url.startswith('graph:'):
        graph_data = map(float, url[6:].split(','))
        return dict(string=generate_graph(graph_data),
                    mime_type='image/png')
    return default_url_fetcher(url)

source = '<img src="graph:42,10.3,87">'
HTML(string=source, url_fetcher=my_fetcher).write_pdf('out.pdf')

Flask-WeasyPrint for Flask and Django-Weasyprint for Django both make use of a custom URL fetcher to integrate WeasyPrint and use the filesystem instead of a network call for static and media files.

A custom fetcher should be returning a dict with

  • One of string (a bytestring) or file_obj (a file object).

  • Optionally: mime_type, a MIME type extracted e.g. from a Content-Type header. If not provided, the type is guessed from the file extension in the URL.

  • Optionally: encoding, a character encoding extracted e.g. from a charset parameter in a Content-Type header

  • Optionally: redirected_url, the actual URL of the resource if there were e.g. HTTP redirects.

  • Optionally: filename, the filename of the resource. Usually derived from the filename parameter in a Content-Disposition header

If a file_obj is given, the resource will be closed automatically by the function internally used by WeasyPrint to retreive data.

Logging

Most errors (unsupported CSS property, missing image, …) are not fatal and will not prevent a document from being rendered.

WeasyPrint uses the logging module from the Python standard library to log these errors and let you know about them. When WeasyPrint is launched in a terminal, logged messaged will go to stderr by default. You can change that by configuring the weasyprint logger object:

import logging
logger = logging.getLogger('weasyprint')
logger.addHandler(logging.FileHandler('/path/to/weasyprint.log'))

The weasyprint.progress logger is used to report the rendering progress. It is useful to get feedback when WeasyPrint is launched in a terminal (using the --verbose or --debug option), or to give this feedback to end users when used as a library.

See the documentation of the logging module for details.

Security

When used with untrusted HTML or untrusted CSS, WeasyPrint can meet security problems. You will need extra configuration in your Python application to avoid high memory use, endless renderings or local files leaks.

This section has been added thanks to the very useful reports and advice from Raz Becker.

Long Renderings

WeasyPrint is pretty slow and can take a long time to render long documents or specially crafted HTML pages.

When WeasyPrint used on a server with HTML or CSS files from untrusted sources, this problem can lead to very long time renderings, with processes with high CPU and memory use. Even small documents may lead to really long rendering times, restricting HTML document size is not enough.

If you use WeasyPrint on a server with HTML or CSS samples coming from untrusted users, you should:

  • limit rendering time and memory use of your process, for example using evil-reload-on-as and harakiri options if you use uWSGI,

  • limit memory use at the OS level, for example with ulimit on Linux,

  • automatically kill the process when it uses too much memory or when the rendering time is too high, by regularly launching a script to do so if no better option is available,

  • truncate and sanitize HTML and CSS input to avoid very long documents and access to external URLs.

Infinite Requests

WeasyPrint can reach files on the network, for example using http:// URIs. For various reasons, HTTP requests may take a long time and lead to problems similar to Long Renderings.

WeasyPrint has a default timeout of 10 seconds for HTTP, HTTPS and FTP resources. This timeout has no effect with other protocols, including access to file:// URIs.

If you use WeasyPrint on a server with HTML or CSS samples coming from untrusted users, or need to reach network resources, you should:

Infinite Loops

WeasyPrint has been hit by a large number of bugs, including infinite loops. Specially crafted HTML and CSS files can quite easily lead to infinite loops and infinite rendering times.

If you use WeasyPrint on a server with HTML or CSS samples coming from untrusted users, you should:

Huge Values

WeasyPrint doesn’t restrict integer and float values used in CSS. Using huge values for some properties (page sizes, font sizes, block sizes) can lead to various problems, including infinite rendering times, huge PDF files, high memory use and crashes.

This problem is really hard to avoid. Even parsing CSS stylesheets and searching for huge values is not enough, as it is quite easy to trick CSS pre-processors using relative units (em and % for example).

If you use WeasyPrint on a server with HTML or CSS samples coming from untrusted users, you should:

Access to Local Files

As any web renderer, WeasyPrint can reach files on the local filesystem using file:// URIs. These files can be shown in img or embed tags for example.

When WeasyPrint used on a server with HTML or CSS files from untrusted sources, this feature may be used to know if files are present on the server filesystem, and to embed them in generated documents.

Unix-like systems also have special local files with infinite size, like /dev/urandom. Referencing these files in HTML or CSS files obviously lead to infinite time renderings.

If you use WeasyPrint on a server with HTML or CSS samples coming from untrusted users, you should:

  • restrict your process access to trusted files using sandboxing solutions,

  • use a custom URL fetcher that doesn’t allow file:// URLs or filters access depending on given paths.

  • follow solutions listed in Long Renderings.

System Information Leaks

WeasyPrint relies on many libraries that can leak hardware and software information. Even when this information looks useless, it can be used by attackers to exploit other security breaches.

Leaks can include (but are not restricted to):

  • locally installed fonts (using font-family and @font-face),

  • network configuration (IPv4 and IPv6 support, IP addressing, firewall configuration, using http:// URIs and tracking time used to render documents),

  • Python, Pango and other libraries versions (implementation details lead to different renderings).

SVG Images

Rendering SVG images more or less suffers from the same problems as the ones listed here for WeasyPrint.

Security advices apply for untrusted SVG files as they apply for untrusted HTML and CSS documents.

Note that WeasyPrint’s URL fetcher is used to render SVG files.