How to Install WeasyPrint in CI Without Pango/Cairo Errors

WeasyPrint installs from pip fine, but it renders HTML to PDF through Pango and Cairo at runtime - so on a slim runner it fails to load libpango/libgobject.

WeasyPrint is a Python HTML-to-PDF renderer that loads the Pango, Cairo, GDK-PixBuf, and HarfBuzz shared libraries at runtime via ctypes. The pip install succeeds with no compiler, but on a slim image the first render fails because those system libraries are absent.

Why it fails in CI

WeasyPrint does not link these libraries at build time - it dlopens them when you render. So pip install passes, then import weasyprint/rendering fails on a slim image with "cannot load library libpango". The fix is installing the GObject/Pango/Cairo runtime libraries.

• cannot load library 'libpango-1.0.so.0' / libgobject-2.0.so.0 at render time.
• OSError from ctypes loading Cairo/Pango on a slim image.
• Fonts missing → blank or boxed glyphs in the PDF output.

Install it reliably

Install the Pango/Cairo/GDK-PixBuf/HarfBuzz runtime libraries (and base fonts) via apt, then pip install WeasyPrint. There is no compiler step - only system libraries.

# Debian/Ubuntu: WeasyPrint runtime system libraries + fonts
apt-get update && apt-get install -y \
  libpango-1.0-0 libpangocairo-1.0-0 libcairo2 \
  libgdk-pixbuf-2.0-0 libffi-dev libharfbuzz0b \
  fonts-liberation

pip install --only-binary=:all: weasyprint

Cache & speed

Cache ~/.cache/pip for the wheel, and bake the Pango/Cairo libraries and fonts into a custom image so apt does not run every job.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-weasyprint-${{ hashFiles('requirements*.txt') }}

Common errors

Key takeaways

• WeasyPrint loads Pango/Cairo at runtime - install them as system libraries.
• pip install passes; the failure surfaces at first render on slim images.
• Install fonts too, and bake the libraries into the image.

Related guides