Registry / data / mineru

mineru

JSON →
library3.3.1pypypiunverified

MinerU is a robust document parsing tool designed to convert various input formats, including PDF, images, DOCX, PPTX, and XLSX, into machine-readable Markdown and JSON. It is optimized for downstream retrieval, extraction, and processing, especially for LLM-ready formats. Currently at version 3.0.9, the library is actively maintained with ongoing architectural enhancements and feature improvements, particularly in handling scientific literature and complex document structures.

pip install -U "mineru[all]"
INSTALL
IMPORT
SIG · MINERU
M
mineru
datapythonv3.3.1
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.3.1 · 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
glibc
py 3.10
✕ build_error
1/4 runs
py 3.11
✕ build_error
1/4 runs
py 3.12
✕ build_error
2/4 runs
py 3.13
✕ build_error
2/4 runs
py 3.9
✕ build_error
✕ build_error
Code
Verified usage

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

parse_doc
from mineru.utils.demo_utils import parse_doc
from mineru import parse_doc
The primary parsing function, `parse_doc`, is often found within `mineru.utils.demo_utils` in examples, rather than directly under the top-level `mineru` package. While direct API access might exist, demo utilities are frequently used for quickstarts.

This quickstart demonstrates how to use MinerU's Python API to convert a local PDF file into Markdown format. It creates an output directory and uses the `parse_doc` function from `mineru.utils.demo_utils`. Users should replace `your_document.pdf` with the actual path to their PDF file. The `backend` parameter can be adjusted for CPU-only (pipeline) or GPU-accelerated (e.g., vlm-transformers) inference.

import os from pathlib import Path from mineru.utils.demo_utils import parse_doc # Create a dummy PDF file for demonstration # In a real scenario, replace 'input.pdf' with your actual PDF file path. # This example assumes you have a 'demo_pdfs' directory with 'demo1.pdf' # or create a placeholder for testing purposes. # Example placeholder for an input PDF file # For a real run, ensure 'your_document.pdf' exists or create it. input_pdf_path = Path("your_document.pdf") # Replace with a real PDF path if not input_pdf_path.exists(): print(f"Warning: '{input_pdf_path}' not found. Please provide a valid PDF for the quickstart.") # Create a dummy file for execution to pass with open(input_pdf_path, 'w') as f: f.write("This is a dummy PDF content for testing.") print(f"Created a dummy '{input_pdf_path}' for demonstration. Parsing might not yield meaningful results.") output_directory = Path("mineru_output") output_directory.mkdir(exist_ok=True) print(f"Parsing {input_pdf_path} to Markdown...") # Parse the document using the pipeline backend (CPU-friendly) # 'lang' can be adjusted, e.g., 'en' for English. # 'backend' can be 'vlm-transformers' for higher accuracy if GPU is available. parse_doc( path_list=[input_pdf_path], output_dir=output_directory, lang="en", backend="pipeline", # Use 'vlm-transformers' or 'vlm-sglang-engine' if GPU is available f_dump_md=True # Output markdown files ) print(f"Parsing complete. Check output in: {output_directory.resolve()}") # Clean up the dummy file if it was created if input_pdf_path.name == "your_document.pdf" and input_pdf_path.exists() and input_pdf_path.stat().st_size < 100: input_pdf_path.unlink()
mineru --version
Debug
Known issues
breakingVersion 2.0 and later removed the `pymupdf` dependency. Code relying on direct `pymupdf` calls or specific behaviors might break.
fix
Review your code for `pymupdf` interactions and adapt to MinerU's native parsing or updated API. Ensure a clean installation to avoid dependency conflicts.
affects: >=2.0.0
gotchaPython 3.13 has limited support on Windows due to underlying dependencies like `ray`. Users on Windows should stick to Python 3.10, 3.11, or 3.12.
fix
Use a Python environment with version 3.10, 3.11, or 3.12 on Windows. Consider Linux or macOS for Python 3.13+ environments if `ray` is a critical dependency.
affects: >=3.0.0
gotchaParsing complex documents may result in inaccurate output for specific elements. Known limitations include reading order in extremely complex layouts, limited vertical text support, recognition issues with uncommon list formats, lack of code block recognition, poor parsing of comic books/art albums/primary school textbooks, table recognition errors in complex tables, and inaccurate OCR for lesser-known languages.
fix
For critical documents with these characteristics, manually review and correct outputs. Consider submitting issues with example files to the MinerU GitHub repository for ongoing improvements. Use `--log-level debug` to gain more insight into parsing steps.
affects: All versions
gotchaWhen parsing multiple PDFs in a loop, especially with the `vllm` backend, users might encounter `PdfiumError ("Failed to import pages")` due to resource exhaustion or `PDFium`'s non-thread-safe nature.
fix
Manually clear GPU memory (`torch.cuda.empty_cache()`, `gc.collect()`), reduce batch size, split large PDFs, or consider the `pipeline` backend for robustness. Upgrade `mineru` and `pypdfium2` to the latest versions for potential stability fixes.
affects: All versions using `vllm` backend
Upgrade
Version history
3.3.1latest on PyPI · released Jun 11, 2026
Audit
Dependencies
PythonrequiredRequired Python version range
rayrequiredSpecific dependency limitation on Windows
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources
mineru — pip install mineru · libregistry