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 mineru document library ships with usage telemetry turned on. It excludes document contents, file names, and paths. Run mineru telemetry disable to turn it off. Telemetry doesn't cover mineru-kit parse.
  • mineru parse stops at 10 pages unless you add --pages all. mineru-kit parse converts the whole file.
  • 4.x drops 3.x extras like mineru[core] and mineru[pipeline], and it ignores old mineru.json configs. 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.