PyPDFium2

Warnings

• breaking In v5.0.0, `PdfDocument.render()` and `PdfBitmap.get_info()` were removed. `PdfDocument.render()` had performance issues due to bitmap transfer overhead in multiprocessing.
  Fix: Use `PdfPage.render()` with a loop or process pool for rendering pages. Retrieve bitmap information directly from the `PdfBitmap` object instead of `PdfBitmap.get_info()`.
• gotcha PDFium is not thread-safe. Simultaneous calls to PDFium functions across different threads (even with different documents) can lead to crashes or corruption.
  Fix: For 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).
• gotcha When 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.
  Fix: Explicitly cast `HDC` objects: `ctypes.cast(your_hdc, pypdfium2.raw.HDC)`.
• gotcha Opening 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.
  Fix: Avoid using password-protected PDFs on these specific architectures or conduct thorough testing before deployment. Consider alternative platforms if this is a critical use case.
• gotcha There 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.
  Fix: Ensure 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.
• breaking Versions 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.
  Fix: Always 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.

Install

• pip install pypdfium2 Install latest stable release

Imports

• 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.

Quickstart

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.")