Install & Compatibility
Where this runs
tested against v6.16.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.605s · 42.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.2s · import 2.070s · 43MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PdfReader
✓ from pypdf import PdfReader
PdfWriter
✓ from pypdf import PdfWriter
PdfMerger
✓ from pypdf import PdfMerger
✗ from PyPDF2 import PdfFileMerger
The library was renamed from PyPDF2 to pypdf, and class names were standardized. `PdfFileMerger` is now `PdfMerger`.
This quickstart demonstrates how to create two simple PDF files and then merge them into a single output PDF using PdfReader and PdfWriter.
from pypdf import PdfReader, PdfWriter
# Create dummy PDF files for the example
with open("document1.pdf", "wb") as f:
writer = PdfWriter()
writer.add_blank_page(width=72, height=72)
writer.add_page(writer.add_blank_page(width=72, height=72))
writer.write(f)
with open("document2.pdf", "wb") as f:
writer = PdfWriter()
writer.add_blank_page(width=72, height=72)
writer.add_page(writer.add_blank_page(width=72, height=72))
writer.write(f)
# Merge multiple PDF files into one
writer = PdfWriter()
# Add pages from document1.pdf
reader1 = PdfReader("document1.pdf")
for page in reader1.pages:
writer.add_page(page)
# Add pages from document2.pdf
reader2 = PdfReader("document2.pdf")
for page in reader2.pages:
writer.add_page(page)
# Write the merged PDF to a new file
with open("merged_document.pdf", "wb") as output_pdf:
writer.write(output_pdf)
print("PDFs merged successfully into merged_document.pdf")
Debug
Known issues
breakingThe library was renamed from PyPDF2 to pypdf. This involved a package name change and significant class and method renames (e.g., `PdfFileReader` to `PdfReader`, `PdfFileWriter` to `PdfWriter`, `PdfFileMerger` to `PdfMerger`, and methods like `getNumPages()` to `len(reader.pages)`).fixUpdate your import statements from `from PyPDF2 import ...` to `from pypdf import ...` and adapt to the new class and method names following PEP8 conventions (e.g., `reader.getNumPages()` becomes `len(reader.pages)`). Consult the migration guide for a full list of changes.
affects: PyPDF2 v2.0.0 (and earlier) to pypdf v3.0.0 (and later)
deprecatedSupport for abbreviations in `decode_stream_data` was deprecated.fixAvoid using abbreviations when calling `decode_stream_data`. Review the official documentation for the recommended usage.
affects: >=6.7.0
gotchaCalling `PageObject.replace_contents()` for pages not assigned to a `PdfWriter` is deprecated. This can lead to unexpected behavior and will be removed in pypdf 7.0.0.fixEnsure that `PageObject.replace_contents()` is only called on `PageObject` instances that are part of a `PdfWriter` object. The documentation advises against using it directly on pages from a `PdfReader`.
affects: >=6.8.0
gotchaOlder versions of pypdf might experience significant performance degradation (O(n²) complexity) when dealing with frequent `NameObject` read/write operations, especially with complex or large PDF files.fixUpgrade to pypdf 6.9.0 or later, which includes performance improvements for `NameObject` handling.
affects: <6.9.0
gotchaProcessing untrusted or malformed PDF files, especially with older versions of pypdf, can lead to security vulnerabilities such as infinite loops, excessive resource consumption, or crashes. Numerous security fixes address issues like circular references and stream length limits.fixKeep `pypdf` updated to the latest version to benefit from security patches. Consider using `strict=True` when initializing `PdfReader` to raise exceptions for non-standard compliant PDFs, allowing for explicit error handling.
affects: All versions, but more critical in older versions prior to recent security patches (e.g., <6.9.2, <6.9.1, <6.8.0, <6.7.x)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pypdf'
The 'pypdf' library is not installed in the current Python environment.
ImportError: cannot import name 'PdfFileReader' from 'pypdf'
The class 'PdfFileReader' was renamed to 'PdfReader' in pypdf version 6 and later, following a major API overhaul.
fixfrom pypdf import PdfReader
# Similarly, PdfFileWriter was renamed to PdfWriter
from pypdf import PdfWriter
AttributeError: 'PdfReader' object has no attribute 'getNumPages'
The methods 'getNumPages()' and 'getPage()' are from the deprecated PyPDF2 API; pypdf v6+ exposes pages as a list-like attribute, 'reader.pages'.
fixfrom pypdf import PdfReader
reader = PdfReader("example.pdf")
num_pages = len(reader.pages) # Get number of pages
first_page = reader.pages[0] # Access a specific page TypeError: 'list' object is not callable
In pypdf v6+, 'reader.pages' is an attribute (a list-like object) that provides access to the PDF pages, not a method to be called.
fixfrom pypdf import PdfReader
reader = PdfReader("example.pdf")
page_count = len(reader.pages) # Access as attribute, not a method Upgrade
Version history
6.16.2latest on PyPI · released Aug 23, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.9 or higher.
PyCryptodomeoptionalNeeded for AES encryption and decryption of PDFs.