Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

4.8 KB
Raw Blame

Quick Start

This guide targets MinerU 4.x, including 4.1 automatic device selection and API updates. Existing deployments should read the 4.1 migration guide. Legacy vendor-accelerator instructions remain scoped to <4; see the legacy platform guides.

Install MinerU

The MinerU package supports Python >=3.11,<3.15. Python 3.12 is a practical starting point for a new environment. Optional engines such as vLLM, LMDeploy, and Torch have additional wheel, OS, and driver constraints; the package's Python range does not guarantee every engine supports that entire range.

uv venv --python 3.12 .venv

Activate on Linux / macOS:

source .venv/bin/activate

Activate in Windows PowerShell:

.venv\Scripts\Activate.ps1

Install the latest published 4.x base package:

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

Alternatively, run python -m pip install -U "mineru>=4.0,<5" in the activated environment. A package mirror can be selected with the installer's -i option.

The base package includes the WebUI, ONNX small-model runtime, and llama.cpp VLM. Apple Silicon automatically includes Torch dependencies. For Torch small models or higher-throughput VLM serving, see extension modules for the torch and full extras. Do not use 3.x extras.

4.1 uses DirectML on Windows x64 and WebGPU on Linux x86_64 to select a compatible GPU or CPU automatically. Apple Silicon defaults to Torch/MPS and llama.cpp/Metal. Use mineru-kit hardware detect for tier recommendations or hardware info --json for diagnostics. Initial ONNX calibration may download the recognition model; see Tiers and runtimes.

First conversion

Parse a single file without a document library and write Markdown to a file:

mineru-kit parse document.pdf -o document.md --tier standard

The first model-backed parse may download weights. For native PDF text extraction without inference models, explicitly select:

mineru-kit parse document.pdf -o document.md --tier flash --ocr-mode txt

This reads the PDF text layer and does not add an OCR fallback for scanned pages. Use --ocr-mode ocr and prepare the relevant models for scanned PDFs.

Native documents and batch conversion:

mineru-kit parse report.docx -o report.md --tier flash
mineru-kit parse ./documents -o ./output --format zip

For directories or multiple inputs, -o must be a directory. For single-file Markdown output, use a file path. mineru-kit parse defaults to all PDF pages.

Document library and agents

mineru parse document.pdf --json
mineru parse document.pdf --pages all -o document.md
mineru search "keyword" --json

mineru uses the document library and cache. mineru parse defaults to the first 10 PDF pages and may return a continuation request when the output reaches its length budget. Follow the returned locator and next_request. This differs from mineru-kit parse, which directly writes complete conversion outputs; see Quick Usage.

Document-library telemetry

Doclib includes usage and diagnostic telemetry, initially enabled. Inspect it with mineru telemetry status or preview, and use mineru telemetry disable to stop collection and sending. Set MINERU_TELEMETRY_DISABLED=1 before server startup when needed. Document contents, file names, and paths are excluded; see telemetry details for scope and controls.

WebUI and API

mineru-kit webui --server-name 127.0.0.1 --server-port 7860

Open the local WebUI. mineru-webui is the standalone command for the same entrypoint. Without --api-url, the WebUI manages a local V1 API server. See SDK and API to connect an existing service.

mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard

Inspect the running service through its OpenAPI documentation. Use Tasks for asynchronous batches; start the separate file-parse service to upload one file and receive an attachment directly.

Install from source

Run from a checkout of the corresponding version:

uv pip install -e .
mineru version --json

Confirm a 4.x version; a development checkout may report a prerelease. For NVIDIA containers, see Docker deployment.

Next steps