Install MinerU 4.0.12: PDF Parsing AI Deploy Guide

The #1 mistake with PDF parsing AI on MinerU 4.x isn’t a bad GPU. It’s running mineru parse right after install and treating quality_tier_unavailable like a broken package. That error means the document-library path wants a managed local parse server – or an explicit tier you already prepared. Reverse the order: install the base package, prove the path with mineru-kit, download models, then turn on managed mode only if you need the library CLI.

MinerU 4.0.12 (11 Oct 2026 per GitHub tags) turns PDFs, scans, Office, EPUB, and more into Markdown/JSON for RAG and agents – local by default. This guide pins that release so you parse today instead of debugging magic-pdf or old mineru -p syntax.

System requirements before you touch pip

Python >=3.10,<3.15. Full stop. Official Quick Start pushes a fresh 3.12 venv; optional engines (vLLM, LMDeploy, Torch) stack their own wheel and driver limits on top of that range.

Do you need a GPU on day zero? Often no – and forcing [full] before a single kit parse just multiplies wheel pain.

If you’re on AMD or other stacks that stayed on mineru<4, don’t force 4.0 mainline. Use the legacy platform guides instead.

Official download source (skip random mirrors)

• PyPI package mineru – pin >=4.0,<5 while 4.0.12 is current
• Source / Dockerfiles: https://github.com/opendatalab/MinerU
• Docs hub: https://opendatalab.github.io/MinerU/

China networks often set MINERU_MODEL_SOURCE=modelscope. Hugging Face is the default auto probe; if HF Xet CAS fails, set HF_HUB_DISABLE_XET=1 before model download (Model Source docs).

Install MinerU 4.0.12 step by step

Path that wastes the least time: uv + base package. GPU extras later.

pip install -U pip uv
uv venv --python 3.12 .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .venvScriptsActivate.ps1

uv pip install -U "mineru>=4.0,<5"
mineru version --json

You want a 4.x string back. Torch small models: uv pip install -U "mineru[torch]>=4.0,<5". Max local serving: "mineru[full]>=4.0,<5" – vLLM on Linux, LMDeploy on Windows per extension modules. Dead 3.x extras ([core]/[pipeline]/[all]) do not define 4.0. Skip them.

Windows + NVIDIA after [torch]/[full]: run python -c "import torch; print(torch.cuda.is_available(), torch.__version__)". Still seeing +cpu? Community setups keep hitting CPU-only wheels – pull the matching CUDA index from pytorch.org.

Pro tip: First success command is always mineru-kit parse, not mineru parse. Kit is stateless conversion. Library CLI expects cache + parse-server capability discovery.

Alternatives in one line each: editable source uv pip install -e . from a 4.0 checkout; NVIDIA Docker docker build -t mineru:4 -f docker/global/Dockerfile . then compose profiles webui/api/router/openai-server (Docker deployment docs). Tag the real version and assert mineru.version inside the image – the Dockerfile installs a range, not your git SHA.

First-time configuration

Config lives in $MINERU_HOME/config.yaml (default ~/.mineru). Old mineru.json is ignored after 4.0.

# Pull weights for the tier you'll run (standard covers advanced model needs)
mineru-kit models download --tier standard
mineru-kit models verify --tier standard
mineru-kit models show

# Optional: ModelScope
# export MINERU_MODEL_SOURCE=modelscope

# Only if you need the document-library CLI path:
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json

Telemetry: mineru telemetry status / disable. Design notes limit it to doclib-related metrics – not file contents or paths. Remote upload is opt-in (--remote). Local failure does not silently ship your PDF.

Verify the install works

The catch is load time, not the command list.

mineru version --json
mineru-kit parse sample.pdf -o sample.md --tier standard
# text-layer only smoke test (no heavy models):
# mineru-kit parse sample.pdf -o sample-flash.md --tier flash --ocr-mode txt

mineru-kit webui --server-name 127.0.0.1 --server-port 7860
# API: mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard
# then open http://127.0.0.1:8000/docs and GET /v1/health

First standard run can sit on weight load for tens of seconds. Later pages move faster. Office/HTML/EPUB inputs want --tier flash (native path per tiers docs).

Ever notice how tools ship two CLIs that look synonymous until one fails loudly on purpose? Here the split is quality and capability discovery – kit stays stateless; library refuses to pretend a tier exists when it doesn’t.

Common install errors and fixes

1. quality_tier_unavailable on mineru parse – Models missing or parse server still disabled. Use kit, or finish download/verify + managed_tier / mode managed. Library will not quietly drop to flash or cloud.
2. CUDA false / slow “GPU” path on Windows – Reinstall Torch from the official CUDA wheel index; confirm torch.cuda.is_available().
3. FileNotFoundError deep under Tempmineru-…ocrimages – Long source filenames + Windows MAX_PATH. Rename to a short path before parse.
4. Model download corrupt / invalid load key – Incomplete cache. Delete bad files, re-run mineru-kit models download + verify; try ModelScope or HF_HUB_DISABLE_XET=1.
5. Docker “Device string must not be empty” – Host lacks NVIDIA Container Toolkit, or driver can’t run the image CUDA (default 13.0 per Docker docs). Fix toolkit/drivers, try the commented cu129 base, or stay on CPU/basic outside GPU containers.
6. API outputs disappear later – 4.0.12 self-hosted API/Router default retention is 24 hours. Set MINERU_API_RETENTION_SECONDS or --retention-seconds (0 disables) and download results in time.

Upgrade from 3.x and uninstall

Stop services first. Fresh venv beats in-place 3→4.

uv pip install -U "mineru>=4.0,<5" # add [torch] or [full] if you had acceleration
mineru version --json
mineru-kit models download --tier standard
mineru-kit models verify --tier standard

Remember the dual CLI? Migration maps old muscle memory like this: mineru -p in -o out → mineru-kit parse in -o out.md (or library mineru parse once managed mode is up); mineru-gradio → mineru-kit webui; -m all → mineru-kit models download --tier standard. Backend names are gone – pick tiers. Legacy result JSON outside Doclib may need a re-parse.

Cleanup:

uv pip uninstall mineru
# remove env folder
rm -rf .venv # or your conda env
# optional data wipe
rm -rf ~/.mineru
# Docker
docker compose -f docker/compose.yaml --profile webui down
docker rmi mineru:4

FAQ

mineru vs mineru-kit – which do I install commands for?

Same package. Kit first for one-shot files. Library CLI after models + managed parse server.

Can I run PDF parsing AI on CPU only?

Yes. Base install already runs ONNX small models on CPU; basic is the tier built for that path.

Scenario: laptop, no dGPU, 50-page scan. Download/verify basic, parse with --tier basic, or use flash + --ocr-mode txt on clean digital PDFs. standard/advanced still work via llama.cpp without a datacenter card – just slower. Minutes per long scan is the tradeoff, not a broken install.

I upgraded and my old scripts still call /file_parse or mineru[core]. What broke?

People assume the old HTTP path and extras names survived. They didn’t.

4.0 rebuilt the surface around V1 (/v1/health, uploads, parse jobs, files). 4.0.12 puts convenience /v1/tasks and /v1/file_parse wrappers back on self-hosted API/Router – but they speak current tier/OCR contracts, not 3.x parameter names. Extras collapsed to base / torch / full. Swap hard-coded historical model IDs for tier selection after you upgrade.

Drop a short-named PDF next to your venv, run mineru-kit parse your.pdf -o your.md --tier standard, and only then decide if you need WebUI, managed server, or Docker. That order survives contact with 4.0.12.