pikepdf

library10.12.0pypypi✓ verified 24d ago

pikepdf is a Python library that enables reading, writing, repairing, and transforming PDF files, leveraging the powerful `qpdf` C++ library. It offers comprehensive PDF manipulation capabilities, including merging, splitting, compressing, and extracting data. Currently at version 10.5.1, it follows a regular release cadence with several minor and patch releases per year.

data serialization

pip install pikepdf

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PIKEPDF

pikepdf

datapythonv10.12.0

Install

3.7s avg

Import

301ms

Disk

59MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v10.12.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.314s · 64MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.288s · 59MB

59MB installed

● package 59MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pdf

✓ from pikepdf import Pdf

Page

✓ from pikepdf import Page

This quickstart demonstrates how to create a new PDF, add pages to it, and then open and modify an existing PDF file using `pikepdf`. The `Pdf` object should always be used within a `with` statement for proper resource management.

from pikepdf import Pdf, Page import os # Create a new PDF and add a blank page output_filename = "my_first_pikepdf.pdf" with Pdf.new() as pdf: pdf.add_blank_page() pdf.save(output_filename) print(f"Created {output_filename} with one blank page.") # Open an existing PDF, add another page, and save it to a new file modified_filename = "my_modified_pikepdf.pdf" with Pdf.open(output_filename) as pdf: pdf.add_blank_page() print(f"PDF now has {len(pdf.pages)} pages.") pdf.save(modified_filename) print(f"Modified PDF saved to {modified_filename}.") # Clean up generated files (optional) # os.remove(output_filename) # os.remove(modified_filename)

Debug

Known issues

gotchapikepdf is a Python wrapper around the `qpdf` C++ library. You must have `qpdf` installed on your system for pikepdf to function. It is not installed via pip.

fix

Install `qpdf` via your system's package manager (e.g., `apt install qpdf` on Debian/Ubuntu, `brew install qpdf` on macOS, or download from qpdf.sourceforge.io for Windows).

affects: All versions

breakingThe `Pdf.read()` method was removed in favor of `Pdf.open()`. Always use `Pdf.open()` and it is strongly recommended to use it as a context manager (`with Pdf.open(...) as pdf:`).

fix

Replace `Pdf.read(filename)` with `with Pdf.open(filename) as pdf:`.

affects: >= 10.0.0

breakingAttributes like `page.trimbox` and `page.cropbox` now return `PageBox` objects instead of simple tuples or lists of numbers. These `PageBox` objects have methods like `pagebox.as_list()` or `pagebox.as_tuple()` to get the raw coordinates.

fix

When accessing page box coordinates, adapt your code from `box[0]` to `box.as_list()[0]` or use `box.left`, `box.bottom`, etc. directly on the `PageBox` object.

affects: >= 10.0.0

gotchaChanges made to a `Pdf` object are not saved until `pdf.save()` is explicitly called. If you modify a PDF and forget to call `save()`, your changes will be lost.

fix

Ensure `pdf.save(output_filename)` is called after all modifications. When using `with Pdf.open(...) as pdf:`, `pdf.save()` should be called within the `with` block.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pikepdf'

The 'pikepdf' library is not installed in the Python environment being used, or the environment is not correctly activated.

fix

pip install pikepdf

ERROR: Failed building wheel for pikepdf

This error occurs during installation when Python's package manager (pip) cannot find pre-built binary wheels for 'pikepdf' and attempts to compile it from source, but lacks the necessary C++ compiler or 'qpdf' development libraries on the system.

fix

Ensure you have a C++ compiler (e.g., Visual Studio Build Tools on Windows, Xcode Command Line Tools on macOS, `build-essential` on Debian/Ubuntu) and the 'qpdf' development libraries installed on your system. For macOS, `brew install qpdf` is often required before `pip install pikepdf`.

pikepdf.PasswordError: Incorrect password

An attempt was made to open a password-protected PDF file using `pikepdf.Pdf.open()` without providing the correct password.

fix

Provide the correct password as an argument to the `open` method: `pdf = pikepdf.Pdf.open('input.pdf', password='your_password')`.

AttributeError: 'pikepdf._core.Pdf' object has no attribute 'check'

This specific `AttributeError` indicates that code is attempting to call the deprecated `pdf.check()` method, which was renamed in 'pikepdf' version 10.x.

fix

Update the method call to `pdf.check_pdf_syntax()`: `messages = pdf.check_pdf_syntax()`.

ImportError: pikepdf's extension library failed to import

This typically occurs when 'pikepdf' is built from source and there's an incompatibility or missing dependency with the underlying 'qpdf' C++ library, often related to C++ ABI compatibility or missing runtime components (e.g., Visual C++ Redistributable on Windows).

fix

First, try installing a pre-built wheel if available: `pip install --force-reinstall pikepdf`. If building from source is necessary, ensure your C++ compiler matches the one used to build Python and `qpdf`, and that all necessary `qpdf` libraries and headers are accessible to the compiler and linker. On Windows, ensure the correct Visual C++ Redistributable is installed.

Upgrade

Version history

10.12.0latest on PyPI · released Aug 17, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

42 hits · last 30 days

node

Resources

githubhttps://github.com/pikepdf/pikepdf ↗

packagehttps://pypi.org/project/pikepdf/ ↗

docshttps://pikepdf.readthedocs.io/ ↗

changeloghttps://pikepdf.readthedocs.io/en/latest/releasenotes/index.html ↗