{"id":684,"library":"pymupdf","title":"PyMuPDF","description":"PyMuPDF is a Python binding for MuPDF, a lightweight PDF, XPS, and E-book viewer, renderer, and toolkit. It provides comprehensive functionalities for handling PDF documents, including reading, writing, rendering pages to images, extracting text, searching, annotating, and manipulating document structure. The library is actively maintained with frequent releases, often tied to updates of the underlying MuPDF library, currently at version 1.27.2.2.","status":"active","version":"1.27.2.2","language":"python","source_language":"en","source_url":"https://github.com/pymupdf/pymupdf","tags":["PDF","document processing","MuPDF","image extraction","text extraction","OCR","vector graphics"],"install":[{"cmd":"pip install --upgrade pymupdf","lang":"bash","label":"Install or upgrade PyMuPDF"}],"dependencies":[],"imports":[{"note":"`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`.","wrong":"import pymupdf; doc = pymupdf.open('file.pdf')","symbol":"fitz","correct":"import fitz"}],"quickstart":{"code":"import fitz # PyMuPDF\n\n# Open a document\ntry:\n    doc = fitz.open(\"input.pdf\") # Replace with your PDF file\nexcept fitz.FileNotFoundError:\n    print(\"PDF file not found. Creating a dummy PDF.\")\n    doc = fitz.open() # Create a new, empty PDF\n    doc.new_page()\n    page = doc[0]\n    page.insert_text(fitz.Point(50, 50), \"Hello, PyMuPDF!\")\n    doc.save(\"input.pdf\")\n    doc.close()\n    doc = fitz.open(\"input.pdf\")\n\n# Get the first page\npage = doc[0]\n\n# Extract text\ntext = page.get_text()\nprint(f\"Extracted text:\\n{text}\")\n\n# Close the document\ndoc.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult the release notes for your target PyMuPDF version and ensure your Python environment matches the supported range. Upgrade or downgrade Python if necessary.","message":"Supported 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.","severity":"breaking","affected_versions":"1.26.5 to 1.26.6, other minor versions may also adjust support."},{"fix":"If 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.","message":"The `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.","severity":"breaking","affected_versions":">=1.26.7"},{"fix":"Review 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.","message":"The 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.","severity":"breaking","affected_versions":">=1.27.2"},{"fix":"Always 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.","message":"Forgetting 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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.","message":"PyMuPDF 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions (related to test environment setup, not library version)"},{"fix":"Ensure 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.","message":"PyMuPDF, 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.","severity":"breaking","affected_versions":"All versions (especially in minimal Linux distributions like Alpine)"}],"env_vars":null,"last_verified":"2026-05-12T17:48:33.722Z","next_check":"2026-07-09T00:00:00.000Z","problems":[{"fix":"First, uninstall any potentially conflicting `fitz` package and `PyMuPDF`, then reinstall `PyMuPDF`. The recommended way to import is `import pymupdf`. If you need to maintain `fitz` in older code, use `import pymupdf as fitz`. Ensure your Python environment (including virtual environments) is clean.","cause":"This error often occurs when an outdated or conflicting `fitz` package is installed alongside `PyMuPDF`, or when using `import fitz` while `pymupdf` is the intended library. `PyMuPDF` uses `fitz` as a legacy alias, but conflicts can arise if a separate `fitz` package exists.","error":"AttributeError: module 'fitz' has no attribute 'open'"},{"fix":"Ensure `pymupdf` is installed using `pip install pymupdf`. Verify that your IDE or terminal is using the correct Python interpreter. If you previously relied on `import fitz`, update your code to `import pymupdf` or `import pymupdf as fitz` for backward compatibility.","cause":"This typically means the PyMuPDF library was not installed correctly, or the Python interpreter running the code is not the one where PyMuPDF was installed. It can also occur if an older `import fitz` is used after installing only `pymupdf`.","error":"ModuleNotFoundError: No module named 'pymupdf'"},{"fix":"Update your code to use the snake_case version of the method. For `loadPage`, change it to `load_page`. Similarly, `new_page` is now `new_page()`. Consult the PyMuPDF documentation for the correct method names for your installed version.","cause":"PyMuPDF transitioned from camelCase to snake_case for many of its method names (e.g., `loadPage` became `load_page`). This error indicates you are using an older method name with a newer version of the library.","error":"AttributeError: 'Document' object has no attribute 'loadPage'"},{"fix":"Ensure you have the necessary build tools (e.g., Visual Studio on Windows, Xcode command line tools on macOS, `build-essential` on Linux). For specific version conflicts with other libraries, try installing a compatible PyMuPDF version, e.g., `pip install PyMuPDF==X.Y.Z`, or downgrade Python to a version for which wheels are available.","cause":"This error occurs during installation when `pip` attempts to build `PyMuPDF` from source because a pre-compiled wheel is not available for your specific operating system, Python version, or architecture. This often requires C/C++ development tools to be installed, or there might be conflicts with other package requirements (e.g., `paddleocr` requiring an older `PyMuPDF` version).","error":"ERROR: Failed building wheel for PyMuPDF"}],"ecosystem":"pypi","meta_description":null,"install_score":50,"install_tag":"draft","quickstart_score":30,"quickstart_tag":"draft","pypi_latest":"1.27.2.3","install_checks":{"last_tested":"2026-05-12","tag":"draft","tag_description":"notable install failures or slow imports","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"78.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.1,"import_time_s":0.31,"mem_mb":16.1,"disk_size":"78M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":16.1,"disk_size":"78M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"81.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.7,"import_time_s":2.57,"mem_mb":18,"disk_size":"81M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.05,"mem_mb":18,"disk_size":"81M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"73.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.6,"import_time_s":1.63,"mem_mb":17.7,"disk_size":"73M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.92,"mem_mb":17.7,"disk_size":"73M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"73.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.7,"import_time_s":1.57,"mem_mb":17.8,"disk_size":"73M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.8,"mem_mb":17.8,"disk_size":"73M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"76.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.2,"import_time_s":0.25,"mem_mb":16.7,"disk_size":"76M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":16.7,"disk_size":"76M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"draft","tag_description":"notable failures across runtimes","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":0}]}}