Install & Compatibility
Where this runs
tested against v0.2.17 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pisa
✓ from xhtml2pdf import pisa
✗ from xhtml2pdf import XML2PDF
The `XML2PDF` and `XHTML2PDF` functions were deprecated in v0.2.7 and are slated for removal. The `pisa.CreatePDF` function is the recommended and widely used entry point for HTML to PDF conversion.
This quickstart demonstrates how to convert an HTML string into a PDF file using `pisa.CreatePDF`. The function takes the HTML content and a file handle (opened in binary write mode) as arguments. It then saves the generated PDF to the specified output file.
from io import BytesIO
from xhtml2pdf import pisa
html_content = '''
<html>
<head>
<style>
@page { size: A4 portrait; margin: 1cm; }
h1 { color: #333; }
p { font-family: sans-serif; }
</style>
</head>
<body>
<h1>Hello from xhtml2pdf!</h1>
<p>This is a simple HTML to PDF conversion example.</p>
<p>Visit <a href="https://github.com/xhtml2pdf/xhtml2pdf">xhtml2pdf on GitHub</a>.</p>
</body>
</html>
'''
def convert_html_to_pdf(source_html, output_filename):
result_file = open(output_filename, 'w+b') # Open in binary write mode
pisa_status = pisa.CreatePDF(
source_html, # the HTML to convert
dest=result_file) # file handle to receive result
result_file.close() # close output file
if pisa_status.err:
print(f"PDF creation failed with errors: {pisa_status.err}")
return False
else:
print(f"PDF created successfully: {output_filename}")
return True
# Example usage:
convert_html_to_pdf(html_content, "example.pdf")
Debug
Known issues
breakingPython 2 support was officially dropped in version 0.2.6. As of version 0.2.12, Python 3.7 is no longer supported either. The library now requires Python 3.8 or newer.fixEnsure your project runs on Python 3.8 or a later version.
affects: >=0.2.6 (Python 2), >=0.2.12 (Python 3.7)
deprecatedThe direct imports `XML2PDF` and `XHTML2PDF` (e.g., `from xhtml2pdf import XML2PDF`) were deprecated in v0.2.7 and are scheduled for removal in future versions. While `HTML2PDF` was mentioned as an alternative, the primary and recommended entry point for conversion is `pisa.CreatePDF`.fixMigrate your code to use `from xhtml2pdf import pisa` and call `pisa.CreatePDF(...)` instead.
affects: >=0.2.7
gotchaCompatibility with `ReportLab` versions is a recurring issue. Specifically, `xhtml2pdf 0.2.16` added compatibility for `reportlab >= 4.1`. Earlier versions like `0.2.12` and `0.2.11` had specific dependencies on `reportlab >= 4.0.4` and `reportlab >=3.5.53,<4` respectively. Mismatched versions can lead to unexpected errors.fixAlways check the `xhtml2pdf` release notes or `pyproject.toml` for the exact `ReportLab` version compatibility, or install `xhtml2pdf` without specifying `ReportLab` to let pip resolve dependencies correctly.
affects: All versions, specifically 0.2.11, 0.2.12, 0.2.16
breakingThe underlying PDF library dependency for merging and other operations has changed. `PyPDF2` was replaced with `PyPDF3` in some earlier 0.2.x releases, and then `PyPDF3` was changed to `pypdf` in version 0.2.9.fixEnsure that `pypdf` is installed in your environment. If you directly import or rely on the underlying PDF library, update your imports/calls from `PyPDF2` or `PyPDF3` to `pypdf`.
affects: >=0.2.9
Errors
Common errors & fixes
UnicodeEncodeError: 'latin-1' codec can't encode character
xhtml2pdf or an underlying component attempts to process input HTML containing non-ASCII characters using an incompatible default encoding, such as `latin-1` or `ascii`.
fixEnsure the input HTML string is explicitly encoded to UTF-8 bytes before passing it to xhtml2pdf, for example: `pisa.CreatePDF(html_string.encode('utf-8'), dest=result_file, encoding='UTF-8')` FileNotFoundError: [Errno 2] No such file or directory: '/static/images/logo.png'
xhtml2pdf cannot locate static assets (images, CSS, fonts) referenced with relative paths in the HTML because it lacks a configured base directory or a callback to resolve these paths on the file system.
fixProvide a `link_callback` function to `pisa.CreatePDF` that translates relative paths found in the HTML to absolute file system paths or URLs where the assets are stored.
ModuleNotFoundError: No module named 'xhtml2pdf'
The `xhtml2pdf` package is not installed in the Python environment where the script is being executed, or the environment's `PYTHONPATH` does not include the installation location.
fixInstall the library using pip in your active Python environment: `pip install xhtml2pdf`
Upgrade
Version history
0.2.17latest on PyPI · released Feb 24, 2025
Audit
Dependencies
reportlabrequiredCore toolkit for PDF generation, handles low-level PDF primitives.
html5librequiredHTML parsing and tree building.
pypdfrequiredPDF manipulation (e.g., joining PDFs).
pycairooptionalRecommended rendering backend for ReportLab, especially for complex text rendering like CJK fonts. Requires system-wide Cairo graphics library.
renderpmoptionalLegacy rendering backend for ReportLab, an alternative to PyCairo.