Install & Compatibility
Where this runs
tested against v5.13.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.212s · 30.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.214s · 27MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pdfium
✓ import pypdfium2 as pdfium
raw
✓ import pypdfium2.raw as pdfium_c
For direct access to the low-level ctypes PDFium API.
internal
✓ import pypdfium2.internal as pdfium_i
For internal utilities, generally not for direct public use.
This quickstart demonstrates how to create a new PDF document with an empty A4 page and save it. It then shows how to open an existing PDF and retrieve basic information. This example is fully runnable without external files, as it creates and cleans up its own dummy PDF.
import pypdfium2 as pdfium
import os
# Create a new, empty PDF document with one A4 page
pdf = pdfium.PdfDocument.new()
page = pdf.new_page(595, 842) # A4 size in points (width, height)
page.close()
output_filename = 'example_output.pdf'
pdf.save(output_filename, version=17)
pdf.close()
print(f"Created PDF: {output_filename}")
# Example of opening an existing PDF and getting info (requires a dummy file)
# To make this runnable, we'll open the one we just created.
if os.path.exists(output_filename):
existing_pdf = pdfium.PdfDocument(output_filename)
print(f"Opened existing PDF with {len(existing_pdf)} pages.")
existing_pdf.close()
os.remove(output_filename) # Clean up the dummy file
print(f"Cleaned up {output_filename}")
else:
print(f"Error: {output_filename} not found for reading example.")
Debug
Known issues
breakingIn v5.0.0, `PdfDocument.render()` and `PdfBitmap.get_info()` were removed. `PdfDocument.render()` had performance issues due to bitmap transfer overhead in multiprocessing.fixUse `PdfPage.render()` with a loop or process pool for rendering pages. Retrieve bitmap information directly from the `PdfBitmap` object instead of `PdfBitmap.get_info()`.
affects: >=5.0.0
gotchaPDFium is not thread-safe. Simultaneous calls to PDFium functions across different threads (even with different documents) can lead to crashes or corruption.fixFor parallelizing expensive PDFium tasks like rendering, use `multiprocessing` (processes) instead of `threading` (threads). If using threads, ensure only one PDFium call is made at a time (e.g., using a mutex).
affects: All versions
gotchaWhen using Windows-only API members included in bindings (from v5.5.0), it is strongly recommended to `ctypes.cast()` your `HDC` object to `pypdfium2.raw.HDC` before passing it to `FPDF_RenderPage()` to ensure type compatibility.fixExplicitly cast `HDC` objects: `ctypes.cast(your_hdc, pypdfium2.raw.HDC)`.
affects: >=5.5.0
gotchaOpening password-protected PDFs on `s390x` and `musllinux_armv7l` architectures is known to be broken (as of v5.6.0). Builds for these platforms are provided but are considered 'use at own risk' with no warranty.fixAvoid using password-protected PDFs on these specific architectures or conduct thorough testing before deployment. Consider alternative platforms if this is a critical use case.
affects: >=5.6.0
gotchaThere is a risk of Python garbage collection prematurely freeing objects that are still needed by PDFium's C API, leading to non-deterministic segmentation faults (dangling object issues). This applies when using the raw API or if Python-managed resources are passed to it.fixEnsure that any Python objects (like byte buffers, callback functions) whose memory is managed by Python but referenced by PDFium's C functions are explicitly kept alive for the entire duration they are needed by PDFium. Reference these objects in an accompanying class or similar mechanism.
affects: All versions
breakingVersions 4.30.1 and 5.0.0b1 were yanked from PyPI due to text extraction regressions in the underlying PDFium library. While specific to older versions, it highlights that underlying PDFium changes can introduce regressions.fixAlways use the latest stable version of `pypdfium2` and consult release notes for any known issues or specific PDFium updates that might affect critical functionality like text extraction or rendering.
affects: 4.30.1, 5.0.0b1 (yanked)
Upgrade
Version history
5.13.0latest on PyPI · released Aug 13, 2026
Audit
Dependencies
PillowoptionalOptional: Provides convenience adapters to translate between raw bitmap buffers and PIL images, used for image saving and some command-line features.
NumPyoptionalOptional: Provides helpers to get a numpy array view of a raw bitmap.
opencv-pythonoptionalOptional: Can be used in the rendering CLI to save with pypdfium2's NumPy adapter.