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
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.fixReview 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.fixUse 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.fixFor 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.fixManually 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