pypdf

pypdf is a free, open-source, pure-Python library for working with PDF files. It can split, merge, crop, and transform pages, add passwords and viewing restrictions, extract text and metadata, and manipulate annotations, bookmarks, and form fields — all without any external binary dependencies like Poppler or MuPDF.

The library grew out of the original PyPDF2 project and has since become the de facto standard pure-Python PDF toolkit, with over 27 million weekly downloads on PyPI. It ships full type hints (mypy strict mode) and a test suite exercising real-world PDF files pulled from a companion sample-files repository, which has made it a dependency of choice for teams that need predictable, dependency-light PDF processing inside Python backends, data pipelines, and document-automation tools.

What You Get

• PdfReader and PdfWriter classes for loading, creating, and saving PDF documents from files, bytes, or streams
• Page-level operations: merge, split, rotate, crop, scale, and overlay/watermark pages via the Transformation API
• Text and metadata extraction, including layout-aware extraction modes for tables and multi-column documents
• Encryption and decryption support (standard and AES, with cryptography or PyCryptodome as optional backends)
• Direct access to the low-level PDF object model (generic module) for advanced manipulation of dictionaries, streams, and cross-reference tables
• Form field (AcroForm) reading and filling, annotation manipulation, and outline/bookmark management
• Full static typing (py.typed, mypy strict) so downstream code gets accurate autocomplete and type checking

Common Use Cases

• Merging or splitting multi-page PDF reports generated by other systems
• Stripping or adding passwords and permissions to PDFs before distribution
• Extracting text and structured metadata from PDFs for search indexing or document pipelines
• Watermarking or stamping generated PDFs (e.g. invoices, contracts) with overlay pages
• Filling and reading AcroForm fields in PDF-based forms as part of document-automation workflows

Under The Hood

Architecture

pypdf splits into a high-level document API (PdfReader and PdfWriter, sharing common logic through a PdfDocCommon mixin) and a low-level PDF object model (dictionaries, arrays, streams, indirect references, cross-reference tables) that both classes operate on directly. Page-level logic (PageObject, Transformation) composes onto that object model rather than duplicating parsing, and stream filtering/decoding (compression, image formats) is isolated from encryption, which is fully separated with pluggable crypto backends. This layered design means most feature work touches the page or object-model layer without needing to change the reader/writer’s core parsing, though the object model is foundational enough that a breaking change there would ripple through nearly every module.

Tech Stack

Pure Python 3.9+ with no mandatory runtime dependencies beyond a typing backport on older interpreters; optional extras (cryptography or PyCryptodome for AES, Pillow for image extraction, fonttools, arabic-reshaper/python-bidi for right-to-left text) are declared as pip extras so consumers only install what they use. The build backend is flit_core with packaging metadata centralized in pyproject.toml, and documentation is built with Sphinx and hosted on Read the Docs.

Code Quality

The test suite is extensive and runs with network access disabled by default, with tests opting into network or “real-world sample” access via explicit markers backed by a companion sample-files repository. CI runs the suite across multiple operating systems and Python versions (including PyPy) with parallelized test execution and coverage upload, plus a dedicated strict-mode type-check pass. Linting is configured to select the full rule set of its linter with an explicit, reasoned set of exceptions rather than a loose default configuration. Combined with full static typing throughout the package, this is a rigorously tooled codebase relative to typical pure-language libraries in its category.

API Design The public surface is deliberately small — only a handful of top-level classes and helpers are exported, keeping a much larger implementation mostly hidden behind two entry points. Getting started requires almost no boilerplate: loading a file and extracting text from its first page is a one-liner. The reader and writer share behavior through a common mixin so both feel consistent, and advanced users can drop into the low-level object model when the high-level API doesn’t cover a case, though that layer demands more familiarity with the PDF specification itself. Errors are raised as a typed hierarchy rather than generic exceptions, which aids programmatic handling upstream.