Install & Compatibility
Where this runs
tested against v1.28.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 81.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 1.398s · 81MB
79MB installed
● package 79MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fitz
✓ import fitz
✗ import pymupdf; doc = pymupdf.open('file.pdf')
`fitz` is the conventional and widely used alias for PyMuPDF, inherited from its original name, 'PyFITS'. While `import pymupdf` also works, most examples and community resources use `fitz`.
This quickstart demonstrates how to open a PDF document (or create a dummy one if not found), extract text from its first page, and then properly close the document. Replace 'input.pdf' with the path to your actual PDF file.
import fitz # PyMuPDF
# Open a document
try:
doc = fitz.open("input.pdf") # Replace with your PDF file
except fitz.FileNotFoundError:
print("PDF file not found. Creating a dummy PDF.")
doc = fitz.open() # Create a new, empty PDF
doc.new_page()
page = doc[0]
page.insert_text(fitz.Point(50, 50), "Hello, PyMuPDF!")
doc.save("input.pdf")
doc.close()
doc = fitz.open("input.pdf")
# Get the first page
page = doc[0]
# Extract text
text = page.get_text()
print(f"Extracted text:\n{text}")
# Close the document
doc.close()
Debug
Known issues
breakingSupported Python versions have changed between minor releases. For instance, version 1.26.5 supported Python 3.9-3.14, while 1.26.6 narrowed this to 3.10-3.14. Always check the release notes for the exact supported Python versions before upgrading, especially in automated environments.fixConsult the release notes for your target PyMuPDF version and ensure your Python environment matches the supported range. Upgrade or downgrade Python if necessary.
affects: 1.26.5 to 1.26.6, other minor versions may also adjust support.
breakingThe `pymupdf embed-extract` command's safety has been improved. It now refuses to write to an existing file or outside the current directory by default, preventing accidental overwrites or unauthorized file creation.fixIf you relied on previous behavior, you must explicitly handle file output, likely by ensuring the target file does not exist or by operating within the designated current directory. Check the documentation for new options to override this safety measure if intended.
affects: >=1.26.7
breakingThe behavior of `get_textpage_ocr()` changed to OCR *all* page areas outside legible text, not just previously limited ones. This can lead to different or more extensive OCR results than in prior versions.fixReview any code that relies on the output of `get_textpage_ocr()` and adjust expectations or post-processing logic to account for potentially more comprehensive OCR data.
affects: >=1.27.2
gotchaForgetting to close document objects (`doc.close()`) can lead to resource leaks (e.g., open file handles) or temporary files not being cleaned up, especially when working with many documents or in long-running processes.fixAlways call `doc.close()` when you are finished with a document. Alternatively, use a `with` statement: `with fitz.open('file.pdf') as doc: ...` to ensure the document is automatically closed. affects: All versions
gotchaPyMuPDF uses a coordinate system where the origin (0,0) is at the top-left corner of the page. Y-coordinates increase downwards, and X-coordinates increase to the right. This can be counter-intuitive for users familiar with bottom-left origin systems.fixAlways remember that `Point(x, y)` and `Rect(x0, y0, x1, y1)` define positions relative to the top-left corner, with `y` increasing as you move down the page.
affects: All versions
gotchaThe test output 'PDF file not found. Creating a dummy PDF.' suggests that a required input PDF file was not present in the test environment, causing the test script to create a placeholder. This is an environmental or test setup issue, not a direct error or breaking change within the PyMuPDF library functionality.fixEnsure that all expected input files for the test script are correctly placed and accessible in the test environment. Review the test setup documentation or script logic for expected file paths.
affects: All versions (related to test environment setup, not library version)
breakingPyMuPDF, being a C/C++ wrapper, requires certain system-level C/C++ runtime libraries (e.g., `libstdc++.so.6`). In minimal environments, such as Alpine Linux, these libraries may not be present by default, leading to `ImportError` during module loading.fixEnsure that your environment includes the necessary C/C++ runtime libraries. For Alpine Linux, this typically means installing `g++` or `libstdc++`. Add `RUN apk add g++` (or `apk add build-base` which includes `g++`) to your Dockerfile or installation script before installing PyMuPDF.
affects: All versions (especially in minimal Linux distributions like Alpine)
Upgrade
Version history
1.28.2latest on PyPI · released Aug 6, 2026
Audit
Dependencies
No dependency data recorded yet.