PyMuPDF

Warnings

• deprecated The legacy import `import fitz` is still available for backward compatibility, but the recommended and official way to import PyMuPDF is `import pymupdf`. Using `import fitz` can lead to `ModuleNotFoundError` if an unmaintained, unrelated `fitz` package from PyPI is installed, causing conflicts.
  Fix: Update your code to use `import pymupdf`. If you have existing code, consider `import pymupdf as fitz` as a temporary measure, but it's best to refactor to `pymupdf`.
• gotcha It is crucial to properly close `Document` objects to prevent memory leaks, especially in long-running applications or when processing many files. Failing to do so can consume significant system resources.
  Fix: Always close `Document` objects using `doc.close()` or, preferably, use them within a `with` statement (e.g., `with pymupdf.open(filename) as doc:`), which ensures automatic closure.
• breaking Many methods and properties have transitioned from `camelCase` (e.g., `pageCount`, `newPage`) to `snake_case` (e.g., `page_count`, `new_page`) starting around version 1.18.14. Old names are deprecated and will be removed in future major versions (e.g., removal planned post 1.19.0 / around 1.20.0).
  Fix: Update your code to use the `snake_case` equivalents for methods and properties. Refer to the official documentation for the updated API.
• breaking PyMuPDF regularly updates its supported Python versions. For example, Python 3.8 support was dropped in a minor release. Upgrading PyMuPDF might unexpectedly break compatibility with older Python environments.
  Fix: Always check the `requires_python` metadata on PyPI or the official documentation before upgrading PyMuPDF, especially in production environments. Pin your Python version accordingly.
• gotcha On Windows, users may encounter `ImportError: DLL load failed while importing _extra` due to missing `MSVCP140.dll`. This often indicates a missing or outdated Microsoft Visual C++ Redistributable package.
  Fix: Install the latest Microsoft Visual C++ Redistributable for Visual Studio from the official Microsoft website.

Install

• pip install --upgrade pymupdf Install PyMuPDF

Imports

• pymupdf

  import pymupdf

  The `fitz` import is a legacy alias for backward compatibility. While it often works, it can cause a `ModuleNotFoundError` or conflicts if an unrelated, unmaintained `fitz` package is installed from PyPI. The recommended and modern import is `import pymupdf`.

Quickstart

This quickstart demonstrates how to open a PDF, iterate through its pages, extract text from each page, and print the collected text. It includes necessary resource management to ensure the document is closed properly and a dummy PDF creation for a self-contained example.

import pymupdf
import os

# Create a dummy PDF file for demonstration purposes
dummy_pdf_content = b"%PDF-1.4\n1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n2 0 obj<</Type/Pages/Count 1/Kids[3 0 R]>>endobj\n3 0 obj<</Type/Page/MediaBox[0 0 612 792]/Contents 4 0 R/Parent 2 0 R>>endobj\n4 0 obj<</Length 57>>stream\nBT\n/F1 24 Tf\n100 700 Td\n(Hello, PyMuPDF!) Tj\nET\nendstream\nendobj\nxref\n0 5\n0000000000 65535 f\n0000000009 00000 n\n0000000052 00000 n\n0000000108 00000 n\n0000000216 00000 n\ntrailer<</Size 5/Root 1 0 R>>startxref\n304\n%%EOF"
with open("example.pdf", "wb") as f:
    f.write(dummy_pdf_content)

# Open a PDF document and extract text
doc = None # Initialize doc to None
try:
    doc = pymupdf.open("example.pdf")
    full_text = []
    for page in doc:
        full_text.append(page.get_text())
    print("Extracted text:\n" + "\n".join(full_text))
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if doc and not doc.is_closed:
        doc.close() # Ensure the document is closed
    if os.path.exists("example.pdf"):
        os.remove("example.pdf") # Clean up the dummy file