{"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,"search_vec":"'1.27.2.2':64 'activ':47 'annot':39 'bind':6 'book':16 'comprehens':23 'current':61 'document':28,42,66 'e':15 'e-book':14 'extract':36,70,72 'frequent':50 'function':24 'graphic':75 'handl':26 'imag':35,69 'includ':29 'librari':45,60 'lightweight':10 'maintain':48 'manipul':41 'mupdf':8,59,68 'ocr':73 'often':52 'page':33 'pdf':11,27,65 'process':67 'provid':22 'pymupdf':1,2 'python':5 'read':30 'releas':51 'render':18,32 'search':38 'structur':43 'text':37,71 'tie':53 'toolkit':20 'under':58 'updat':55 'vector':74 'version':63 'viewer':17 'write':31 'xps':12","created_at":"2026-03-28T17:10:23.669576+00:00","updated_at":"2026-04-16T18:34:24.351173+00:00","problems":{"verify_error":"error: unexpected argument '--upgrade pymupdf' found\n\n  tip: a similar argument exists: '--upgrade'\n\nUsage: uv pip install --upgrade <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>\n\nFor more information, try '--help'."},"ecosystem":"pypi","meta_description":null,"install_score":50,"quickstart_score":30,"quickstart_tag":"draft","pypi_latest":"1.28.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pymupdf/pymupdf","docs":"https://pymupdf.readthedocs.io/","changelog":"https://pymupdf.readthedocs.io/en/latest/changes.html","pypi":"https://pypi.org/project/pymupdf/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"draft"}}