PyMuPDF

A high-performance Python library for extracting, rendering, converting, and manipulating PDF and other document formats.

Library
PyPI
v2.1
11,080 stars
GNU AGPLv3

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
91 /100 Excellent
Development Activity 100
Maintenance 96
Community 68
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
78 /100 Good
Architecture 78
Code Quality 82
Innovation 70
Learning Curve 80

PyMuPDF is a Python binding for MuPDF, a lightweight and fast C library for parsing and rendering PDF, XPS, EPUB, and other document formats. It gives Python code low-level, pixel-accurate control over document content — text with full font/position/color metadata, embedded images, vector graphics, and page structure — alongside high-level convenience methods for common tasks like text extraction, table detection, annotation, redaction, and page rendering to images.

With no mandatory external dependencies and prebuilt wheels for Windows, macOS, and Linux, it installs with a single pip install pymupdf and is used heavily in document-processing pipelines, from traditional text extraction to LLM/RAG ingestion workflows via its companion package PyMuPDF4LLM. The project ships as open source under AGPL-3.0, with an optional commercial license (PyMuPDF Pro) unlocking Office-format conversion (DOCX, XLSX, PPTX) for teams that can’t comply with AGPL’s copyleft terms.

What You Get

  • Text extraction as plain text, structured dicts with font/size/color/bbox metadata, HTML, XML, or raw blocks
  • Table detection via find_tables(), exportable directly to Markdown or a Pandas DataFrame
  • Page rendering to high-resolution Pixmap images at any DPI, plus SVG vector output
  • Annotation, highlighting, and redaction APIs, including add_redact_annot() / apply_redactions() for permanently removing sensitive content
  • Document assembly operations — merge, split, insert, and reorder pages across PDFs
  • OCR integration via Tesseract for extracting text from scanned pages

Common Use Cases

  • Building document-ingestion pipelines that extract text and layout for search indexing or RAG/LLM retrieval
  • Rendering PDF pages to images for thumbnails, previews, or downstream computer-vision processing
  • Redacting sensitive fields (SSNs, account numbers) from contracts and forms before sharing externally
  • Merging, splitting, and reassembling PDFs as part of an automated document-generation workflow
  • Extracting tabular data from PDF reports and invoices into structured Pandas DataFrames

Under The Hood

Architecture

PyMuPDF is a thin, ergonomic Python layer over MuPDF, a C rendering engine vendored and built from source at install time (see setup.py’s MuPDF download/build step and the pipcl-based pyproject.toml build backend). The public API lives in src/ (pymupdf.py, utils.py, table.py, plus SWIG-generated bindings), with an older compatibility surface preserved separately in src_classic/ for backward compatibility with pre-rename fitz imports (fitz___init__.py, fitz_utils.py). Document, Page, and Pixmap objects wrap MuPDF’s C structs directly, so most operations are thin dispatches into the underlying engine rather than reimplemented logic — the core abstraction to understand is this C-to-Python boundary: changing it means touching the SWIG interface files (extra.i) and rebuilding the native extension, not just editing Python.

Tech Stack

The project builds a bundled MuPDF C/C++ library via a custom pipcl-based PEP-517 backend (no setuptools/hatchling), producing platform wheels for Windows, macOS, and Linux across Python 3.10-3.14. Optional companion packages extend it without adding mandatory dependencies: pymupdf-fonts for extended font coverage, pymupdf4llm for Markdown/RAG-oriented extraction, and pymupdfpro for Office-format (DOCX/XLSX/PPTX) conversion gated behind a commercial license key. Table extraction integrates optionally with Pandas; OCR integrates optionally with a system Tesseract install.

Code Quality

The repo carries an extensive test suite (76+ files under tests/, driven by pytest.ini with --tb=native) and a correspondingly heavy CI setup — seven separate GitHub Actions workflows covering standard tests, a matrix across Python versions (test_multiple.yml), Pyodide/WASM builds, system-installed MuPDF builds, Valgrind memory checks, and wheel builds for every supported platform. This level of CI investment is unusual for a Python package and reflects the project’s need to validate a compiled C extension across many platform/Python combinations, not just pure-Python logic.

What Makes It Unique

PyMuPDF’s differentiator is that it exposes MuPDF’s C-level performance and accuracy (pixel-perfect text positioning, font/color metadata, fast rasterization) through a Pythonic API, rather than shelling out to a CLI tool or relying on a pure-Python PDF parser. Its redaction API removes content from the underlying stream rather than just overlaying it visually, and its ecosystem of companion packages (pymupdf4llm for RAG, pymupdfpro for Office formats) lets it scale from simple text extraction up to full document-conversion pipelines without changing the core library.

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers