Install & Compatibility
Where this runs
tested against v69.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 80.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.000s · 82MB
81MB installed
● package 81MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HTML
✓ from weasyprint import HTML
CSS
✓ from weasyprint import HTML, CSS
default_url_fetcher
✓ from weasyprint import default_url_fetcher
✗ default_url_fetcher(url)
`default_url_fetcher()` is deprecated in v68.0. For custom URL fetching, use the new `URLFetcher` class. Returning dicts from custom fetchers will be removed in v69.0.
This quickstart demonstrates how to convert a simple HTML string with embedded CSS into a PDF file using WeasyPrint. You can also load HTML from a URL or a local file. The `write_pdf` method saves the rendered document to the specified filename.
from weasyprint import HTML, CSS
html_content = """
<!DOCTYPE html>
<html>
<head>
<title>My Document</title>
<style>
@page { size: A4; margin: 2cm; }
body { font-family: sans-serif; }
h1 { color: #336699; }
p { line-height: 1.5; }
</style>
</head>
<body>
<h1>Hello, WeasyPrint!</h1>
<p>This is a test document generated from HTML and CSS into a PDF.</p>
<img src="https://weasyprint.org/static/logo.png" alt="WeasyPrint Logo">
</body>
</html>
"""
# You can also load from a URL: HTML('https://weasyprint.org/')
# Or from a file: HTML(filename='my_document.html')
# Create an HTML object from a string
html = HTML(string=html_content)
# Optionally, add external CSS (or inline as shown above)
# css = CSS(filename='style.css') # or CSS(string='body { font-size: 12pt; }')
# Write the PDF to a file
html.write_pdf('output.pdf')
print("PDF generated successfully as output.pdf")
weasyprint --version
Debug
Known issues
breakingWeasyPrint versions 67.0 and higher require Python 3.10 or newer. Python 3.9 and older are no longer supported.fixUpgrade your Python environment to 3.10 or later. Consider using a virtual environment.
affects: >=67.0
breakingThe `default_url_fetcher()` function is deprecated since v68.0 and will be removed in v69.0. Additionally, custom URL fetchers returning dictionaries are deprecated; they should return `URLFetcherResponse` objects instead.fixMigrate custom URL fetchers to use the new `URLFetcher` class and ensure they return `URLFetcherResponse` instances.
affects: >=68.0 (deprecation), >=69.0 (removal)
breakingWeasyPrint 63.0 replaced its underlying HTML parsing library `html5lib` with `tinyhtml5`. While `tinyhtml5` is a fork of `html5lib`, specific advanced features or internal APIs of `html5lib` may no longer be available or behave differently.fixUpdate your code to be compatible with `tinyhtml5` if you were relying on `html5lib`-specific behaviors or public APIs other than basic parsing. Review the `tinyhtml5` documentation for differences.
affects: >=63.0
gotchaWeasyPrint relies on external system libraries like Pango, Cairo, and GDK-Pixbuf (often provided by GTK+ on Windows) for rendering. These are *not* installed by `pip` and must be installed separately based on your operating system.fixConsult the WeasyPrint documentation for platform-specific installation instructions for these system dependencies (e.g., `apt install libpango-1.0-0` on Debian/Ubuntu, `brew install pango libffi` on macOS, or MSYS2/GTK+ on Windows).
affects: All versions
gotchaUsing WeasyPrint with untrusted HTML or CSS can lead to various security vulnerabilities, including local file access, system information leaks, and infinite network requests/loops.fixSanitize all untrusted input thoroughly. For server-side usage, implement a custom URL fetcher with strict access controls and timeouts, and be mindful of `file://` URIs.
affects: All versions
gotchaSome antivirus software may incorrectly flag WeasyPrint as malware (false positive).fixReport the false positive to your antivirus vendor. This is a known issue documented by the WeasyPrint team.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'weasyprint'
The WeasyPrint library has not been installed in the current Python environment.
fixpip install WeasyPrint
WARNING: Failed to load stylesheet at (...absolute or relative path...)
WeasyPrint could not locate the specified CSS file or image, often due to incorrect relative paths or a missing `base_url` parameter when generating from an HTML string.
fixEnsure the resource paths are correct and provide a `base_url` parameter to `weasyprint.HTML` when rendering HTML content with relative paths from a string, e.g., `HTML(string=html_content, base_url='/path/to/your/files/').write_pdf(...)`.
RuntimeError: Fontconfig error: Cannot open default config file
The necessary Fontconfig libraries and configuration are missing or incorrectly set up on the operating system, which is required for font rendering.
fixInstall Fontconfig and related packages for your OS (e.g., `sudo apt-get install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 fontconfig` on Debian/Ubuntu, `sudo yum install fontconfig pango cairo` on Fedora/RHEL).
ImportError: DLL load failed while importing _cairo: The specified module could not be found.
On Windows, the underlying C libraries (Cairo, Pango, HarfBuzz, GDK-Pixbuf) required by WeasyPrint are not installed or cannot be found in the system's PATH.
fixInstall a pre-compiled GTK+ bundle (e.g., from `https://github.com/tschoonj/GTK-for-Windows-Runtime-Installer/releases`), ensuring its `bin` directory is added to your system's PATH, or use a package manager like MSYS2 to install the necessary development libraries.
Upgrade
Version history
69.0latest on PyPI · released Jun 2, 2026
Audit
Dependencies
PythonrequiredWeasyPrint requires Python 3.10+.
PangorequiredCrucial for text and font rendering, a system-level dependency.
CairorequiredUsed for graphical rendering, a system-level dependency.
GTK+requiredProvides Pango and Cairo on Windows, and other core graphical libraries.
tinycss2requiredRequired for CSS parsing (version 1.5.0+ from v67.0).
fontToolsrequiredRequired for font handling (version 4.59.2+ from v67.0).
tinyhtml5requiredRequired for HTML parsing (replaces html5lib from v63.0, version 2.0.0b1+ from v67.0).
cssselect2requiredRequired for CSS selector matching (version 0.8.0+ from v65.0).
pydyfrequiredRequired for PDF generation backend (version 0.11.0+ from v63.0).