I'm building an AI education project. I need to convert PDFs into Markdown, extract images from pages, and keep math formulas as LaTeX. Most tools I tried choke on the formulas or lose the images. Many want you to upload files to their server. MinerU handles all three on my own machine, and my files stay on it.
MinerU 4.x changed the commands. Older guides use mineru -p input.pdf, -b pipeline, and mineru-gradio. Those are 3.x commands, and they fail on the current release. This guide uses 4.x.
What It Does
- Converts PDF, images, Word, PowerPoint, Excel, EPUB, HTML, and a few more formats into Markdown or structured JSON
- Turns math formulas into LaTeX and tables into HTML
- Saves images from the document as separate files and links them from the Markdown
- Reads scanned pages and multi-column layouts, and merges tables that span pages
- Runs offline on CPU or GPU, including Apple Silicon
- Uses a custom open source license based on Apache 2.0
Install
You need Python 3.11 to 3.14. I use 3.12 in a fresh virtual environment:
pip install uv
uv venv --python 3.12 .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
uv pip install -U "mineru>=4.0,<5"
The base package includes the WebUI and the local model runtimes (ONNX and llama.cpp). On Apple Silicon it pulls in PyTorch too.
Check your hardware before the first parse:
mineru-kit hardware detect
MinerU looks at your CPU and GPU and recommends a parsing tier.
Your first parse downloads the model weights: about 2 GB for the standard tier, under 1 GB for basic. After that you can parse offline. If Hugging Face is slow or blocked where you are, switch the source:
export MINERU_MODEL_SOURCE=modelscope
Usage (CLI)
Convert one file:
mineru-kit parse paper.pdf -o paper.md --tier standard
To save the extracted images as files, export a ZIP:
mineru-kit parse paper.pdf -o ./output --format zip
The package contains:
markdown.md # Markdown, image links use relative paths
images/ # extracted figures, tables, equations
middle_json.json # full structured result
structured_content.json # simpler structured JSON
Point it at a folder to batch-convert:
mineru-kit parse ./documents -o ./output --format zip
Pick a tier
4.x replaced the old pipeline, vlm, and hybrid backends with four tiers:
flash: fastest. Reads the PDF text layer. Good for previews and Office files.basic: small OCR, formula, and table models. Runs fine on CPU.standard: small models plus a VLM. The maintainers recommend it as the default for PDFs.advanced: more VLM work on hard layouts, plus image and chart descriptions. Slowest of the four.
On a CPU-only machine, start with --tier basic.
MinerU parses Word, PPT, and Excel files at flash. It reads their native text, so you don't trade away accuracy:
mineru-kit parse report.docx -o report.md --tier flash
For a quick text-only pass on a digital PDF:
mineru-kit parse paper.pdf -o paper.md --tier flash --ocr-mode txt
This mode skips OCR, so scanned pages come back empty.
Web UI (Gradio)
MinerU comes with a browser interface. In 4.x you start it with one command, and it launches its own local API server:
export NO_PROXY=127.0.0.1,localhost # needed if you run a system proxy
mineru-kit webui --server-name 127.0.0.1 --server-port 7860
Open http://127.0.0.1:7860 and upload a PDF. You see the source and the result side by side, plus a layout view that shows what MinerU detected on each page.
If other tools need to call the API, run it yourself and point the WebUI at it.
Terminal 1 (keep running):
mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard
Terminal 2:
mineru-kit webui --server-name 127.0.0.1 --server-port 7860 --api-url http://127.0.0.1:8000
The API docs are at http://127.0.0.1:8000/docs.
Use It From Claude Code or Codex
MinerU ships an official agent skill. Install it once, and your agent picks MinerU when it has to read a PDF or Office file:
npx skills add opendatalab/MinerU --skill mineru --global --yes
The skill drives the mineru command (no -kit), which keeps a local document library with a cache:
mineru server start
mineru parse paper.pdf --json
mineru parse reads the first 10 pages and returns a pointer to the next chunk. MinerU gives each page and block a stable locator your agent can cite. Your agent can work through a long PDF piece by piece without filling its context.
You'll find community MCP servers for MinerU too. Check how each one parses before you install it. Some, like mineru-mcp, call MinerU's cloud API with an API key and upload your files. If you want everything local, use the skill, or pick a server that talks to your own mineru-kit api-server.
Caveats
- On Apple Silicon, MinerU recommends at least 16 GB of unified memory.
- The
minerudocument library ships with usage telemetry turned on. It excludes document contents, file names, and paths. Runmineru telemetry disableto turn it off. Telemetry doesn't covermineru-kit parse. mineru parsestops at 10 pages unless you add--pages all.mineru-kit parseconverts the whole file.- 4.x drops 3.x extras like
mineru[core]andmineru[pipeline], and it ignores oldmineru.jsonconfigs. Upgrade in a fresh environment.
Demo
I drag in a math-heavy PDF and get Markdown back, with formulas in LaTeX and images saved as files.
Links
- GitHub: https://github.com/opendatalab/MinerU
- Quick start (4.x): https://opendatalab.github.io/MinerU/quick_start/
- Tier guide from the maintainers: https://github.com/opendatalab/MinerU/discussions/5709

