PyPIAI / MLupdated 08 Aug 2026

pymupdf-layout

Item: pymupdf-layout
Rating: 2.8
Author: Keyoor

PyMuPDF Layout is Artifex's local machine-learning layout engine for PyMuPDF. Importing pymupdf.layout loads bundled ONNX graph models and registers a layout callback that PyMuPDF and PyMuPDF4LLM use to identify reading order, headings, headers, footers, text styles, images, and tables from PDF internals. It runs on CPU without a cloud API or GPU. The package is mostly an engine component; PyMuPDF4LLM supplies the documented Markdown, JSON, and text extraction interface most applications actually call.

pymupdf-layout · v1.28.2 · 6.0M/wk · ★ 0 · pushed 06 Aug 2026 · ArtifexSoftware/pymupdf_layout · docs · reviewed by Keyoor

Verdict

Do not install PyMuPDF Layout as if it were a general PDF API. Choose it through PyMuPDF4LLM when local layout-aware extraction is worth the native model footprint and the AGPL or commercial-license terms fit your product.

API stability2/5The package is new, tightly version-pins PyMuPDF 1.28.2, performs activation through the internal pymupdf._get_layout callback, and exposes low-level model construction from source without presenting that as a stable user contract. The safer application API belongs to PyMuPDF4LLM. Matching 1.28.x versions reduce immediate mismatch, but direct integration points should be treated as internal.

Docs2/5The PyPI and GitHub README clearly describe CPU-only layout analysis, structured output goals, and the relationship to PyMuPDF4LLM. It does not document installation platforms, direct return types, model lifecycle, resource use, error handling, or a standalone extraction workflow. The useful examples and option reference live under PyMuPDF4LLM rather than this package.

Maintenance4/5Version 1.28.2 was uploaded August 6, 2026 and the source repository was pushed the same day. Artifex publishes matching wheels for five major platform and architecture combinations, exact integration with current PyMuPDF, tests, native sources, and model resources. The repository is extremely new with zero stars and one open issue or pull request, so long-term cadence is not established.

Ecosystem3/5Its practical ecosystem comes from PyMuPDF and PyMuPDF4LLM, which connect layout results to Markdown, JSON, text, page chunks, images, OCR, LlamaIndex, LangChain, and retrieval pipelines. The engine itself has no plugin community or independent adapter surface, requires an exact PyMuPDF version, and ships only selected CPython wheels, limiting direct reuse outside Artifex's stack.

Use it if

You use current PyMuPDF4LLM layout mode and want local reading-order and table analysis without sending documents to a hosted model
Your PDFs contain multi-column text, repeated headers or footers, and tables that plain text-block extraction orders poorly
You can deploy one of the supplied CPython wheels on x86-64 or ARM64 Linux, Intel or Apple Silicon macOS, or 64-bit Windows
Your distribution can comply with AGPL 3.0 or you have arranged an Artifex commercial license

Skip it if

Your application is proprietary and cannot meet AGPL obligations: PyPI identifies the package as dual-licensed under AGPL 3.0 or an Artifex commercial license
You only need ordinary PDF text extraction or rendering: base PyMuPDF avoids the ONNX model, NumPy, ONNX Runtime, NetworkX, and roughly 43 MB platform wheel
You expect a standalone high-level API: the package README tells users to consume it through PyMuPDF4LLM and barely documents direct model calls
You deploy PyPy, 32-bit systems, musl-only Alpine images, or an unsupported CPU: 1.28.2 publishes CPython abi3 wheels only for listed mainstream platforms and no source distribution
You need OCR by installing this package alone: layout analysis uses PDF structure, while scanned pages still need an OCR engine configured through PyMuPDF4LLM

Setup reality

PyMuPDF Layout 1.28.2 requires CPython 3.10 or newer. PyPI publishes five CPython abi3 wheels: macOS Intel, macOS ARM64, manylinux 2.28 x86-64, manylinux 2.28 ARM64, and Windows x86-64. Each wheel is about 43 MB and bundles native extensions and ONNX model resources; there is no source distribution in the 1.28.2 release, so an unlisted platform cannot simply compile from the PyPI tarball. Dependencies include an exact PyMuPDF==1.28.2 pin plus NumPy, onnxruntime, NetworkX, and PyYAML. That exact pin can force a PyMuPDF upgrade or downgrade and should be tested beside any other library that constrains PyMuPDF. Importing pymupdf.layout is not a passive declaration: its module-level activate call loads a model and assigns PyMuPDF's internal layout callback. First import and first document analysis therefore cost more CPU and memory than ordinary PyMuPDF extraction. The public README presents no normal end-user conversion call and directs readers to PyMuPDF4LLM, whose install already brings PyMuPDF Layout. In most applications install pymupdf4llm and call to_markdown, to_json, or to_text rather than depending on this component directly. Layout mode improves document structure but does not make probabilistic table boundaries or reading order infallible, so keep representative golden PDFs in tests. Scanned text requires Tesseract or rapidocr_onnxruntime through the higher-level OCR path. Multiprocessing model controls exist in low-level source but are not the stable, documented application interface. Finally, settle licensing before deployment: AGPL 3.0 can require source availability for network use, while closed-source distribution generally needs Artifex's commercial terms and legal review.

Patterns

Activate layout support in PyMuPDFactivate-layout-engine

import pymupdf
import pymupdf.layout

doc = pymupdf.open("document.pdf")
page_layout = doc[0].get_layout()

Importing pymupdf.layout loads and registers the bundled model. The direct layout result is lower-level than PyMuPDF4LLM output.

Convert a document to layout-aware Markdownextract-layout-markdown

import pymupdf4llm

markdown = pymupdf4llm.to_markdown("document.pdf")

Install pymupdf4llm for this public API; its current install brings PyMuPDF Layout automatically.

Extract structured JSON outputextract-layout-json

import pymupdf4llm

data = pymupdf4llm.to_json("document.pdf")
print(data)

JSON output includes layout elements and bounding-box information for custom downstream processing.

Extract reading-ordered plain textextract-plain-text

import pymupdf4llm

text = pymupdf4llm.to_text("document.pdf")

Plain text discards Markdown structure; use Markdown or JSON when headings, tables, or coordinates matter.

Process selected zero-based pagesextract-selected-pages

import pymupdf4llm

markdown = pymupdf4llm.to_markdown(
    "document.pdf",
    pages=[0, 1, 5],
)

Page indexes are zero-based. Selecting pages avoids analyzing an entire large document.

Return per-page chunks for retrievalcreate-page-chunks

import pymupdf4llm

chunks = pymupdf4llm.to_markdown("document.pdf", page_chunks=True)
for chunk in chunks:
    page_number = chunk["metadata"]["page_number"]
    index_document(page_number, chunk["text"])

Page chunks also carry document and layout metadata; page boundaries are not automatically ideal semantic chunk boundaries.

Save images referenced by Markdownwrite-extracted-images

import pymupdf4llm

markdown = pymupdf4llm.to_markdown(
    "document.pdf",
    write_images=True,
    image_path="./images",
    image_format="png",
    dpi=150,
)

Create and secure the output directory yourself, and expect document-controlled filenames and additional disk use.

Adjust layout grouping confidencetune-layout-grouping

import pymupdf4llm

markdown = pymupdf4llm.to_markdown(
    "multi-column.pdf",
    edge_threshold=0.75,
)

edge_threshold is passed to page.get_layout; tune it against representative golden documents rather than one sample.

Keep layout mode but emit HTML tablesrender-html-tables

import pymupdf4llm

markdown = pymupdf4llm.to_markdown(
    "tables.pdf",
    table_output="html",
)

This changes table rendering while retaining the layout pipeline for reading order and body text.

Run layout extraction without OCRdisable-document-ocr

import pymupdf4llm

markdown = pymupdf4llm.to_markdown(
    "digital-only.pdf",
    use_ocr=False,
)

Image-only pages return empty text when OCR is disabled; the layout package alone does not recognize scanned characters.

Alternatives

Package	Registry	Pick it when
pymupdf4llm	PyPI	You want the supported high-level Markdown, JSON, text, page chunk, image, and OCR interface that installs this engine for you
pdfplumber	PyPI	You want transparent rule-based PDF text and table extraction without a bundled neural layout model
docling	PyPI	You need a broader document-conversion pipeline with richer format and model orchestration
unstructured	PyPI	You process many document formats and accept a larger partitioning and inference stack