Install & Compatibility
Where this runs
tested against v3.0.1 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.852s · 96.6MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.1s · import 1.064s · 23MB
85MB installed
● package 85MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PdfReader
✓ from PyPDF2 import PdfReader
✗ from pypdf import PdfReader
PdfWriter
✓ from PyPDF2 import PdfWriter
✗ from pypdf import PdfWriter
This quickstart demonstrates basic PDF operations (reading, extracting text, merging, and adding pages) using `pypdf`, the actively maintained successor to `PyPDF2`. It creates a dummy PDF if one doesn't exist for the example to run.
from pypdf import PdfReader, PdfWriter
import os
# Create a dummy PDF for demonstration if it doesn't exist
dummy_pdf_path = "example.pdf"
if not os.path.exists(dummy_pdf_path):
writer = PdfWriter()
writer.add_blank_page(width=72, height=72)
writer.add_blank_page(width=72, height=72)
with open(dummy_pdf_path, "wb") as f:
writer.write(f)
# --- Example: Read, extract text, and merge pages using pypdf (successor to PyPDF2) ---
# Create a PdfReader object
reader = PdfReader(dummy_pdf_path)
# Get number of pages
num_pages = len(reader.pages)
print(f"Number of pages: {num_pages}")
# Extract text from the first page
first_page = reader.pages[0]
text = first_page.extract_text()
print(f"Text from first page: '{text.strip() if text else 'No text'}'")
# Create a PdfWriter object for merging
writer = PdfWriter()
# Add all pages from the reader to the writer
for page in reader.pages:
writer.add_page(page)
# Add a blank page
writer.add_blank_page(width=72, height=72)
# Write the output PDF to a file
output_pdf_path = "merged_output.pdf"
with open(output_pdf_path, "wb") as fp:
writer.write(fp)
print(f"Successfully created {output_pdf_path} with {len(writer.pages)} pages.")
# Clean up dummy file
os.remove(dummy_pdf_path)
os.remove(output_pdf_path)
Debug
Known issues
breakingThe `PyPDF2` project has been officially renamed to `pypdf` and is now actively maintained under that name. The `pypdf2` PyPI package (version 3.0.1) is deprecated and acts as a wrapper around an older version of `pypdf` (specifically, `pypdf` 3.0.1). Users are strongly advised to migrate to `pypdf` for ongoing support, new features, and critical security updates.fixUninstall `pypdf2` (`pip uninstall pypdf2`), then install `pypdf` (`pip install pypdf`). Update import statements and class names in your code.
affects: All `pypdf2` versions
breakingPrior to `PyPDF2` version 3.0.0 (which became the `pypdf` 3.0.1 wrapper), the API involved `import PyPDF2` and class names like `PyPDF2.PdfFileReader` and `PyPDF2.PdfFileWriter`. The modern `pypdf` API (and the `pypdf2 >= 3.0.0` wrapper) uses `from pypdf import PdfReader, PdfWriter` and respective class names.fixUpdate imports to `from pypdf import PdfReader, PdfWriter` and rename class instances (e.g., `PdfFileReader` to `PdfReader`, `PdfFileWriter` to `PdfWriter`).
affects: PyPDF2 < 3.0.0
gotchaOlder versions of `PyPDF2` (pre-3.0.0, i.e., those that are not the `pypdf` 3.0.1 wrapper) contain known performance issues and critical security vulnerabilities, including infinite loop exploits and denial-of-service vectors. Even `pypdf2` 3.0.1, while wrapping `pypdf` 3.0.1, is significantly behind the latest `pypdf` (currently 6.x.x), which has received numerous security patches and performance improvements. Continuing to use `pypdf2` is not recommended for security-sensitive applications.fixMigrate to the latest `pypdf` release (`pip install --upgrade pypdf`) to benefit from crucial security fixes and performance enhancements.
affects: All `PyPDF2` versions; `pypdf2` 3.0.1 (compared to latest `pypdf`)
gotchaThe history of Python PDF libraries is complex, with several forks and renames including `pyPdf`, `PyPDF2`, `PyPDF3`, and `PyPDF4`. This can lead to significant confusion regarding which library is current and actively maintained. `pypdf` (the successor to `PyPDF2`) is the currently recommended and actively developed library.fixAlways use `pip install pypdf` and refer to the official `pypdf` documentation to ensure you are using the correct and most up-to-date library.
affects: All users of Python PDF libraries
deprecatedThe method `PageObject.replace_contents` was documented as potentially problematic and its usage on `PdfReader` objects was specifically advised against in `pypdf` 6.8.0. Incorrect usage can lead to unintended side effects or corrupted PDF files.fixReview your code for `replace_contents` usage. Consult the `pypdf` documentation for alternative approaches or ensure you are using it only as intended by the library maintainers.
affects: `pypdf` (and thus `pypdf2` wrapper) versions 6.8.0 and higher where `replace_contents` is used in a potentially problematic way.
Upgrade
Version history
3.0.1latest on PyPI · released Dec 31, 2022
Audit
Dependencies
PyCryptodomeoptionalRequired for AES encryption and decryption if the 'crypto' extra is installed with pypdf.