pymupdf-stubs

What it is and what it does

pymupdf-stubs is a PEP 561 stub-only package that provides type annotations for PyMuPDF, the Python binding for MuPDF used to read and manipulate PDF documents. It enables static type checkers like mypy to understand PyMuPDF's API surface without adding runtime overhead. The stubs support both the pymupdf and fitz module names (fitz is a compatibility re-export).

Installing the stubs requires no changes to existing code—you install the package and run your type checker. Some highly dynamic PyMuPDF APIs may still be typed as Any or broad dictionary shapes, and the maintainer welcomes issues for missing or incorrect type annotations. The package targets current PyMuPDF releases and is actively maintained.

Use it for:

• Enable mypy or other type checkers to validate PDF processing code written with PyMuPDF.
• Catch type errors in document manipulation workflows before runtime.
• Improve IDE autocomplete and inline documentation for PyMuPDF methods and classes.
• Support fitz-based legacy code with modern type-checking tooling.
• Validate type safety in PDF extraction and transformation pipelines.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides type stubs for PyMuPDF to enable static type checking of PDF document manipulation code without runtime overhead.

Yes, if you use PyMuPDF and want static type checking. The package is actively maintained, has no security vulnerabilities, carries a permissive license, and adds no runtime cost. The main caveat is that some dynamic PyMuPDF APIs may not be fully typed, so you may encounter Any types in edge cases—check the repository if you need comprehensive coverage for your specific use case.

Install

pymupdf-stubs on PyPI

pip install pymupdf-stubs

uv add pymupdf-stubs

poetry add pymupdf-stubs

Installing pymupdf-stubs

Before you install

Active maintenance with a release 4 days ago; low install friction as a stub-only package with a single runtime dependency on pymupdf.

License in practice

Apache-2.0 permissive license allows use in most projects without significant restrictions.

Quickstart

pip install pymupdf-stubs

import pymupdf

doc = pymupdf.Document()
page = doc[0]
drawings = page.get_drawings()

Requires Python 3.12 or later; pymupdf must be installed separately as the runtime dependency.

Verify before relying

• Coverage completeness: whether all PyMuPDF APIs are typed or if significant portions remain as Any/broad dictionaries.
• Compatibility lag: how quickly stubs are updated when PyMuPDF releases new versions.

Package facts

Evidence: pymupdf_stubs-1.28.2-py3-none-any.whl

Keywords: fitz, mupdf, mypy, pdf, pymupdf, stubs, type hints, typing

Tags

More Python Modules packages