Registry / llm-agents / pymupdf4llm

pymupdf4llm

JSON →
library1.28.2pypypi✓ verified 27d ago

PyMuPDF4LLM (also aliased as `pdf4llm`) is a Python library built on PyMuPDF, specialized in converting PDF documents into clean, structured data formats like Markdown, JSON, and plain text, specifically optimized for Large Language Model (LLM) and Retrieval-Augmented Generation (RAG) environments. It includes layout analysis, automatic OCR for scanned pages, and supports multi-column layouts and image extraction. The library is actively maintained and frequently updated, with the current stable version being 1.27.2.2.

pip install -U pymupdf4llm
INSTALL
IMPORT
SIG · PYMUPDF4LLM
P
pymupdf4llm
llm-agentspythonv1.28.2
Install
8.4s avg
Import
2318ms
Disk
169MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.4 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 82.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 8.4s · import 2.318s · 334MB
169MB installed
● package 169MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

to_markdown
import pymupdf4llm md_text = pymupdf4llm.to_markdown("input.pdf")
to_json
import pymupdf4llm json_text = pymupdf4llm.to_json("input.pdf")
to_text
import pymupdf4llm plain_text = pymupdf4llm.to_text("input.pdf")

This quickstart demonstrates how to convert a PDF document into Markdown format using `pymupdf4llm.to_markdown()`. It also shows how to save the output to a file. The library can also convert to JSON and plain text using `to_json()` and `to_text()` respectively.

import pymupdf4llm import pathlib # Assuming 'input.pdf' exists in the same directory # For real-world use, replace with a valid path or PyMuPDF Document object input_pdf_path = "example.pdf" # Create a dummy PDF for demonstration if it doesn't exist # In a real scenario, you would have your actual PDF file try: import fitz # PyMuPDF doc = fitz.open() page = doc.new_page() page.insert_text((72, 72), "# Hello, PyMuPDF4LLM!\n\nThis is a sample PDF content.\n\n- Item 1\n- Item 2\n\n| Header 1 | Header 2 |\n|----------|----------|\n| Data 1 | Data 2 |", fontsize=12) doc.save(input_pdf_path) doc.close() except ImportError: print("PyMuPDF not installed, cannot create dummy PDF. Please provide a real PDF.") input_pdf_path = None if input_pdf_path and pathlib.Path(input_pdf_path).exists(): # Convert the PDF content to Markdown md_text = pymupdf4llm.to_markdown(input_pdf_path) # Print the converted markdown content print("\n--- Markdown Output ---") print(md_text) # Optionally, write it to a markdown file output_md_path = pathlib.Path("output.md") output_md_path.write_text(md_text, encoding="utf-8") print(f"\nMarkdown saved to {output_md_path.absolute()}") else: print("Skipping quickstart as no PDF file is available.")
pdf4llm --version
Debug
Known issues
gotchaPage numbering in PyMuPDF4LLM (and PyMuPDF) is 0-based. Users expecting 1-based indexing for page selection or output references should adjust their logic accordingly.
fix
Remember that the first page is page 0. When using the `pages` parameter, provide 0-based page numbers (e.g., `pages=[0, 2, 4]` for the 1st, 3rd, and 5th pages).
affects: All versions
gotchaFor full OCR functionality (e.g., on scanned PDFs), an external Tesseract OCR engine must be installed and accessible on the system PATH, even though PyMuPDF4LLM handles automatic detection and invocation.
fix
Install Tesseract OCR on your operating system. For Python-side integration, install the `[ocr]` extras (`pip install 'pymupdf4llm[ocr]'`) which includes `opencv-python` for detection heuristics and optional OCR plugins like RapidOCR/PaddleOCR.
affects: All versions
gotchaWhile PyMuPDF4LLM excels at structured extraction, complex layouts such as deeply nested lists, certain table types without clear vertical borders, and link conversion (where the entire line might become a hyperlink) may not always be perfectly preserved in Markdown output.
fix
Review the generated Markdown for documents with highly intricate or unconventional layouts and manually adjust if specific formatting is critical. The JSON output for tables often provides more structured data if fidelity is paramount.
affects: All versions
gotchaThe exclusion of page headers and footers (e.g., using `header=False`, `footer=False`) is currently not applicable when generating JSON output, as JSON aims to represent all data for the included pages.
fix
If header/footer exclusion is critical, process the document into Markdown or plain text, or perform post-processing on the JSON output to remove unwanted sections programmatically.
affects: All versions
breakingPyMuPDF (and by extension PyMuPDF4LLM), being a C++-based library, requires the C++ standard library (`libstdc++.so.6`). This library is often missing in minimalist Linux distributions or musl-based Docker images like Alpine Linux, leading to an `ImportError` upon import.
fix
To resolve the `ImportError: Error loading shared library libstdc++.so.6`, ensure that `libstdc++` is installed in your environment. For Alpine Linux, add `apk add libstdc++` to your Dockerfile or installation commands. For other Linux distributions, use the appropriate package manager (e.g., `apt-get install libstdc++6` for Debian/Ubuntu, `yum install libstdc++` for CentOS/RHEL). Alternatively, consider using a glibc-based Python Docker image (e.g., `python:3.x-slim` or `python:3.x` based on Debian/Ubuntu) which typically includes these dependencies.
affects: All versions
Upgrade
Version history
1.28.2latest on PyPI · released Aug 6, 2026
Audit
Dependencies
PyMuPDFrequiredCore dependency for PDF processing, automatically installed.
pymupdf-layoutrequiredFor advanced layout analysis, automatically installed and activated with pymupdf4llm.
opencv-pythonoptionalRequired for automatic OCR detection heuristics in PyMuPDF-Layout mode. Part of the '[ocr]' extra.
Tesseract OCR engineoptionalExternal dependency required on the system for OCR functionality.
RapidOCRoptionalOptional OCR plugin for improved OCR via the '[ocr]' extra.
PaddleOCRoptionalOptional OCR plugin, especially for CJK languages, via the '[ocr]' extra.
Agent activity
53 hits · last 30 days
node
48
OpenAI (training)
1
Resources
pymupdf4llm — pip install pymupdf4llm · libregistry