Mineru Pdf

MinerU PDF Extraction

Overview

MinerU is a document parsing engine that handles what pypdf/pdfplumber cannot: math formulas, reading order in multi-column layouts, image extraction with position metadata, and scanned PDFs. It runs entirely locally (no API keys, no network after model download).

This skill is for content extraction only. For PDF editing (merge, split, rotate, watermark, encrypt, forms), defer to the standard pdf skill.

Workflow

1. Check installation

pip show mineru

If not installed:

pip install "mineru[pipeline]"

First run downloads models (~2 GB). If HuggingFace is slow or blocked, switch to ModelScope (China mirror):

export MINERU_MODEL_SOURCE=modelscope   # macOS / Linux
$env:MINERU_MODEL_SOURCE="modelscope"   # Windows PowerShell

This uses modelscope.cn instead of huggingface.co — significantly faster inside China. The env var only needs to be set once before the first mineru command.

2. Run MinerU

mineru -p "FILE" -o "OUTPUT_DIR/" -b pipeline

Key options (explain to user when relevant):

| Flag | When to use | |------|-------------| | -l en | Non-Chinese documents (default is ch) | | -f False | Skip formula recognition to save time when no formulas | | -t False | Skip table recognition when no tables | | -s N -e M | Process only a page range |

3. Report results

After extraction completes, summarize for the user:

• How many pages processed
• Output directory and key files
• Count of images, equations, tables extracted
• Flag anything unusual (e.g., empty pages, missing content)

Output Structure

OUTPUT_DIR//auto/
├── .md              # Structured Markdown
├── _content_list.json  # Element metadata
├── _model.json      # Layout detection results
├── _middle.json     # Intermediate processing data
└── images/                    # Extracted images (JPG)

The Markdown preserves document structure (headings, reading order, image references). The JSON provides per-element type, bbox, page_idx, and text — useful for downstream processing.

Performance

First run downloads models (~2GB) from HuggingFace, cached permanently. Subsequent runs skip this step.

| PDF Type | ~Time | |----------|-------| | 10-page text-only | 1 min | | 7-page academic paper (formulas + figures) | 3 min | | 30-page scanned chapter | 10-15 min |

CPU-only environments work but are slower. A GPU speeds up layout detection and formula recognition significantly.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hawkongz
• Source: hawkongz/mineru-pdf
• License: MIT

Install and usage instructions live in the source repository linked above.