| name | mineru-pdf-parser |
| description | Parse complex PDFs (and images / DOCX / PPTX / XLSX) into LLM-ready
Markdown + structured JSON with MinerU — tables, formulas, and reading
order preserved. Use for research ingestion, RAG data prep, and academic
papers / technical reports where layout fidelity matters. Triggers:
"PDF解析", "PDF转Markdown", "提取PDF表格/公式", "parse this PDF",
"MinerU". NOT for reading a few pages (just read them), or for
merge/split/rotate/fill/OCR-in-place — use the `pdf` skill for those.
|
MinerU PDF Parser
Wraps the MinerU CLI (PyPI mineru, v3.4.0 verified 2026-07). CLI-only — there is no stable from mineru import MinerU Python API; drive it via the mineru command.
Why MinerU over the alternatives: PyMuPDF4LLM is AGPL and Marker is GPL — both license blockers for most codebases. MarkItDown's pdfminer.six backend loses heading levels (~0% retention on structured docs). Docling (MIT, ~3s/page on CPU) is the legitimate fallback if MinerU install fails.
Install
uv pip install -U "mineru[core]"
uvx --from "mineru[core]" mineru --help
Usage
mineru -p <input> -o <output_dir>
mineru -p paper.pdf -o out -b pipeline
mineru -p big.pdf -o out -s 0 -e 49
Backend selection (-b, default hybrid-engine)
| Backend | Trait | Pick when |
|---|
pipeline | Most general, runs pure-CPU | No GPU, simple/text PDFs, OCR langs via -l |
hybrid-engine | Default; high accuracy, local compute | GPU/Apple-Silicon box; --effort high adds image/chart analysis |
vlm-engine | VLM high accuracy, local compute | GPU box, formula/table-dense papers |
vlm-http-client / hybrid-http-client | Offload to OpenAI-compatible server via -u <url> | Remote vLLM/SGLang/LMDeploy deployment |
Other flags: -m auto|txt|ocr (pipeline/hybrid only), -f/-t formula/table toggles (default on), --effort medium|high (hybrid only; medium skips image/chart analysis).
First run — model download
Models auto-download from HuggingFace on first parse (large; looks like a hang — tell the user). If HF is blocked: export MINERU_MODEL_SOURCE=modelscope. Pre-fetch with mineru-models-download -s auto -m all. CUDA/MPS acceleration is auto-attempted on Linux/macOS.
Output (per input file, under the output dir)
{name}.md — the LLM-ready Markdown{name}_content_list.json — structured blocks in reading order (RAG-friendly){name}_middle.json — intermediate detail (debugging){name}_layout.pdf (+ {name}_span.pdf, pipeline only) — visual QC of layout/reading order- exact file set varies by backend; see output docs
Pitfalls
| Pitfall | Handling |
|---|
| First run "hangs" | It's the model download — pre-announce; pre-fetch with mineru-models-download |
| No GPU, default backend crawls | Force -b pipeline (the only pure-CPU-safe backend) |
| Scanned PDFs | Quality tracks scan clarity; retry once with another backend, then report honestly — don't silently deliver garbage |
| Hundreds of pages | Memory pressure — parse in -s/-e ranges or split the file first |
| Heading-swallow | A section title rendered as emphasized text inside a table cell isn't detected as a layout heading — consecutive identical ## headers appear with no separating context. Recover by cross-referencing an anchor value (account number, opening balance, figure caption) against the source page |
Before declaring done: confirm {name}.md + {name}_content_list.json exist (report actual paths), and spot-check 1–2 pages against the original for lost/garbled tables and formulas. Also check:
- Compression ratio — a text-born PDF should compress ~5-10x into Markdown; a scan should barely shrink. A ratio outside that range means OCR silently no-op'd or the parse collapsed.
- Dedupe — if two differently-named PDFs produce byte-identical or equal-length Markdown, md5 the source files before reporting — MinerU does not dedupe inputs.
Mandatory human review (don't deliver unchecked): complex math (LaTeX export is lossy), archival needs that preserve page numbers/headers/footers (parsers strip them), and legal/financial/medical documents (sample back-check against the source PDF is required, not optional).
