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
304MB installed
● package 304MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
layout
✓ import pymupdf.layout
Must be imported *before* pymupdf4llm to activate layout features.
pymupdf4llm
✓ import pymupdf4llm
pymupdf
✓ import pymupdf
Used for opening PDF documents, e.g., pymupdf.open('document.pdf').
This quickstart demonstrates how to use PyMuPDF Layout in conjunction with PyMuPDF4LLM to extract structured data from a PDF. It highlights the critical import order of `pymupdf.layout` before `pymupdf4llm` to enable layout analysis. The example creates a simple PDF, then extracts its content into Markdown and JSON formats.
import pymupdf # For document opening
import pymupdf.layout # Crucial: import layout before pymupdf4llm
import pymupdf4llm # For structured data extraction
import os
# Create a dummy PDF file for demonstration
doc = pymupdf.open()
p = doc.new_page()
p.insert_text((50, 50), "Header text\n", fontname="helv", fontsize=12)
p.insert_text((50, 80), "This is a sample paragraph. It demonstrates basic text extraction.")
p.insert_text((50, 110), "Another paragraph with some more content to showcase layout analysis.")
doc.save("sample_document.pdf")
doc.close()
# Open the document with PyMuPDF
document = pymupdf.open("sample_document.pdf")
# Extract structured data as Markdown
markdown_output = pymupdf4llm.to_markdown(document)
print("\n--- Markdown Output ---")
print(markdown_output)
# Extract structured data as JSON (note: header/footer filtering not applicable to JSON)
json_output = pymupdf4llm.to_json(document)
print("\n--- JSON Output ---")
# For brevity, print only a part of the JSON structure if it's large
import json
print(json.dumps(json_output, indent=2))
# Remove the dummy file
os.remove("sample_document.pdf")
Debug
Known issues
gotchaThe `pymupdf.layout` module *must* be imported before `pymupdf4llm` to ensure that PyMuPDF's layout analysis features are activated. If the order is incorrect, `pymupdf4llm` will run without layout enhancement.fixEnsure `import pymupdf.layout` appears before `import pymupdf4llm` in your code.
affects: All versions
gotchaThe `header=False` and `footer=False` parameters for omitting headers and footers are not applicable when extracting data using `pymupdf4llm.to_json()`. The JSON output is designed to be a comprehensive representation of all page data.fixIf header/footer exclusion is needed, process JSON output manually or use `to_markdown()` or `to_text()` with the respective parameters.
affects: All versions
breakingPrior to `pymupdf4llm` version 1.27, `pymupdf-layout` had to be explicitly installed and imported. Since `pymupdf4llm` v1.27, `pymupdf-layout` is automatically installed and used, simplifying the setup but changing the dependency structure.fixFor older `pymupdf4llm` versions, explicitly `pip install pymupdf-layout` and `import pymupdf.layout`. For v1.27+, `pip install pymupdf4llm` is often sufficient, but explicitly importing `pymupdf.layout` is still good practice to ensure activation.
affects: Versions of `pymupdf4llm` before 1.27
gotchaPyMuPDF Layout is licensed under PolyForm Noncommercial, which restricts commercial use. Review the license terms carefully for your specific application.fixConsult the PolyForm Noncommercial license for details. For commercial use, contact Artifex Software for alternative licensing options.
affects: All versions
gotchaFor advanced document types (e.g., Office documents like DOCX, XLSX, PPTX), `PyMuPDF Pro` is required in addition to `PyMuPDF4LLM` to enable processing. PyMuPDF Layout itself primarily enhances PDF processing.fixIf processing non-PDF document formats, ensure you have the appropriate `PyMuPDF Pro` license and package installed alongside `pymupdf4llm`.
affects: All versions
Upgrade
Version history
1.28.2latest on PyPI · released Aug 6, 2026
Audit
Dependencies
pymupdfrequiredCore PDF library for document manipulation and parsing, on which PyMuPDF4LLM and PyMuPDF Layout are built.
pymupdf4llmrequiredProvides the high-level API (to_markdown, to_json, to_text) for structured data extraction, enhanced by PyMuPDF Layout's analysis. Required for most use cases.
numpyrequiredUsed for internal checks, replacing a previous OpenCV dependency within PyMuPDF4LLM.
tesseract-ocroptionalRequired for OCR capabilities if pages need optical character recognition.
pymupdf-prooptionalRequired to extend supported file types to Office document formats (DOC/DOCX, XLS/XLSX, PPT/PPTX, HWP/HWPX) when used with PyMuPDF4LLM.