{"id":933,"library":"pypdfium2","title":"PyPDFium2","description":"pypdfium2 is an ABI-level Python 3 binding to PDFium, a powerful and liberal-licensed library for PDF rendering, inspection, manipulation, and creation. It provides both low-level ctypes-based access to the raw PDFium API and a higher-level Pythonic support model for common use cases. The library is actively maintained, with frequent updates often tied to new PDFium versions, and the current version is 5.6.0.","status":"active","version":"5.6.0","language":"python","source_language":"en","source_url":"https://github.com/pypdfium2-team/pypdfium2","tags":["PDF","bindings","rendering","manipulation","ctypes","document processing"],"install":[{"cmd":"pip install pypdfium2","lang":"bash","label":"Install latest stable release"}],"dependencies":[{"reason":"Optional: Provides convenience adapters to translate between raw bitmap buffers and PIL images, used for image saving and some command-line features.","package":"Pillow","optional":true},{"reason":"Optional: Provides helpers to get a numpy array view of a raw bitmap.","package":"NumPy","optional":true},{"reason":"Optional: Can be used in the rendering CLI to save with pypdfium2's NumPy adapter.","package":"opencv-python","optional":true}],"imports":[{"symbol":"pdfium","correct":"import pypdfium2 as pdfium"},{"note":"For direct access to the low-level ctypes PDFium API.","symbol":"raw","correct":"import pypdfium2.raw as pdfium_c"},{"note":"For internal utilities, generally not for direct public use.","symbol":"internal","correct":"import pypdfium2.internal as pdfium_i"}],"quickstart":{"code":"import pypdfium2 as pdfium\nimport os\n\n# Create a new, empty PDF document with one A4 page\npdf = pdfium.PdfDocument.new()\npage = pdf.new_page(595, 842) # A4 size in points (width, height)\npage.close()\n\noutput_filename = 'example_output.pdf'\npdf.save(output_filename, version=17)\npdf.close()\n\nprint(f\"Created PDF: {output_filename}\")\n\n# Example of opening an existing PDF and getting info (requires a dummy file)\n# To make this runnable, we'll open the one we just created.\nif os.path.exists(output_filename):\n    existing_pdf = pdfium.PdfDocument(output_filename)\n    print(f\"Opened existing PDF with {len(existing_pdf)} pages.\")\n    existing_pdf.close()\n    os.remove(output_filename) # Clean up the dummy file\n    print(f\"Cleaned up {output_filename}\")\nelse:\n    print(f\"Error: {output_filename} not found for reading example.\")","lang":"python","description":"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."},"warnings":[{"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()`.","message":"In v5.0.0, `PdfDocument.render()` and `PdfBitmap.get_info()` were removed. `PdfDocument.render()` had performance issues due to bitmap transfer overhead in multiprocessing.","severity":"breaking","affected_versions":">=5.0.0"},{"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).","message":"PDFium is not thread-safe. Simultaneous calls to PDFium functions across different threads (even with different documents) can lead to crashes or corruption.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly cast `HDC` objects: `ctypes.cast(your_hdc, pypdfium2.raw.HDC)`.","message":"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.","severity":"gotcha","affected_versions":">=5.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"4.30.1, 5.0.0b1 (yanked)"}],"env_vars":null,"last_verified":"2026-05-12T21:28:05.133Z","next_check":"2026-06-27T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.8.0","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.8,"disk_size":"28.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.8,"disk_size":"28.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.08,"mem_mb":3.8,"disk_size":"27M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3.8,"disk_size":"27M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":4.5,"disk_size":"30.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":4.5,"disk_size":"30.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2,"import_time_s":0.33,"mem_mb":4.5,"disk_size":"29M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":4.5,"disk_size":"28M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":4.4,"disk_size":"22.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":4.4,"disk_size":"22.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.24,"mem_mb":4.4,"disk_size":"20M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":4.4,"disk_size":"20M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.6,"disk_size":"22.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":4.5,"disk_size":"21.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.23,"mem_mb":4.6,"disk_size":"20M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":4.5,"disk_size":"20M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.8,"disk_size":"27.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.7,"disk_size":"27.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.1,"mem_mb":3.8,"disk_size":"26M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.8,"disk_size":"26M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}