MinerU Rust
Parse PDF, image, and Office documents into clean Markdown with MinerU: a Rust client library, command-line tools, and a local API server. PDF rendering is pure Rust and needs no native PDF runtime such as PDFium.
The MinerU VLM model can run in two ways:
- Remote — point the tools at an OpenAI-compatible MinerU VLM service and parse documents without running a model on your own machine.
- Local (optional) — serve a quantized MinerU model yourself with llama.cpp
(
llama-server) and point the tools at it; see Docker.
Within the MinerU 3.4.4 VLM scope, MinerU Rust is a drop-in replacement for the
MinerU Python SDK's vlm-http-client path and can replace that VLM workflow
completely. It does not implement or claim compatibility with non-VLM backends.
See the compatibility contract, the
Chinese usage guide, and the English usage guide.
Document-limit controls and their CLI/API applicability are summarized in the usage guides.
The remote protocol is pinned to the MinerU vlm-http-client transport
baseline, so a MinerU-compatible VLM endpoint is required — a general-purpose
chat model will not produce layout results.
Requires Rust 1.89 or newer.
Quickstart
Configure the VLM service with three environment variables:
| Variable | Meaning | Example |
|---|---|---|
MINERU_VL_SERVER |
VLM service base URL | https://host/v1 |
MINERU_VL_MODEL_NAME |
Model ID | model-id |
MINERU_VL_API_KEY |
Bearer token | your-key |
Install the mineru command with Cargo, pip, or npm:
Then parse a document:
Your markdown appears in out/. Find a usable model ID with GET /v1/models
on your endpoint. On success the out/ directory contains document.md,
document.json, middle.json, content_list.json, cropped assets/, and a
layout preview {stem}_layout.pdf.
Prefer the MINERU_VL_API_KEY environment variable over --api-key so the
key does not end up in shell history.
Local: serve the model with llama.cpp
Run the compose llama-server profile (or start llama-server yourself with a
quantized MinerU GGUF model), then point MINERU_VL_SERVER at
http://localhost:30000/v1. See Docker.
Rust library
use ;
async
Python
Wheels support CPython 3.9 and newer. Install with uv or pip:
# or: pip install mineru-rs
parse() returns the markdown string in memory; save it yourself:
= await
await
run() writes the full output tree to an output directory instead (see the
English usage guide). The wheel installs two equivalent
console commands, mineru and mineru-rs; prefer mineru-rs when the
upstream Python mineru package is also installed, since both provide a
mineru entry point and the one earlier on PATH wins. Releases are wheels
only; there is no sdist or source fallback for unsupported platforms or PyPy.
The Python wheel does not bundle the mineru-office-convert helper: Office
format (.docx/.pptx/.xlsx) input is not yet supported in the binding and
fails with "office conversion is unavailable". PDF and image input are
unaffected; use the Rust CLI (cargo install mineru --features office) or
mineru-api for Office conversion.
Node.js
Requires Node.js 18 or newer. Install with pnpm or npm:
# or: npm install @alexsun-top/mineru
import { writeFile } from 'node:fs/promises'
import mineru from '@alexsun-top/mineru'
const { markdown } = await mineru.parse({ path: 'input.pdf' })
await writeFile('out.md', markdown)
run({ path, output }) writes the full output tree to output instead (see
the English usage guide). The root package installs two
equivalent binaries, mineru and mineru-rs, both pointing at
bin/mineru.js; prefer mineru-rs if another mineru command is already on
PATH.
The npm packages do not bundle the mineru-office-convert helper: Office
format (.docx/.pptx/.xlsx) input is not yet supported in the binding and
fails with "office conversion is unavailable". PDF and image input are
unaffected; use the Rust CLI (cargo install mineru --features office) or
mineru-api for Office conversion.
CLI and API server
The package installs the mineru and mineru-api binaries. To also install
the mineru-office-convert Office conversion helper, build with --features office:
mineru-api is the HTTP API server: it accepts documents, calls the
configured VLM, and returns result archives. It performs no local inference.
Submit a document as an async task and fetch the result:
# poll the returned status_url, then download result_url
The mineru client can submit through a running server:
--api-key can pass a Bearer token, but prefer MINERU_VL_API_KEY: a key on
the command line is visible in the process list.
See the Chinese usage guide or English usage guide for service configuration and complete options.
Install
- crates.io —
cargo install mineru(add--features officefor the Office helper; requires Rust 1.89+). - Python —
pip install mineru-rs(CPython 3.9+). - Node.js —
npm install @alexsun-top/mineru(Node.js 18+). - Docker — see Docker.
Build from source:
As a library in your own project: cargo add mineru.
The binaries
| Binary | Purpose |
|---|---|
mineru |
Canonical CLI: PDF, image, and Office documents, either directly against a VLM or through a mineru-api server. |
mineru-api |
HTTP API server (see above). |
mineru-office-convert |
Office (.docx/.pptx/.xlsx) → PDF conversion helper used by mineru; built with --features office. |
Docker
Docker Compose profiles
The bundled docker-compose.yaml runs the MinerU
OpenAI-compatible server on an NVIDIA GPU behind one of two profiles:
| Profile | Image | Purpose |
|---|---|---|
openai-server |
alexsuntop/mineru:3.4.2 |
vLLM-backed MinerU server (default, port 30000). |
llama-server |
ghcr.io/ggml-org/llama.cpp:server-cuda |
llama.cpp server for quantized (GGUF) MinerU models, port 30000. |
Start the vLLM server:
Start the quantized llama.cpp server. Put your GGUF file(s) in ./models
(or set LLAMA_MODELS_DIR), then point LLAMA_MODEL at the container path:
LLAMA_MODEL=/models/mineru-q4_k_m.gguf \
# or fetch from Hugging Face without local files:
# LLAMA_ARG_HF_REPO=your-org/mineru-gguf:Q4_K_M docker compose --profile llama-server up -d
Both server profiles expose http://localhost:30000 (override with
MINERU_PORT_OVERRIDE_VLLM / MINERU_PORT_OVERRIDE_LLAMA); they map the same
host port, so start only one at a time.
COMPOSE_PROFILES can also activate a profile implicitly, e.g.
COMPOSE_PROFILES=llama-server docker compose up -d.
There is no CPU Docker image.
Examples
- examples/python-uv — Python with
uv - examples/node-pnpm — Node.js with
pnpm
Build and test
License
MIT OR Apache-2.0. Model weights downloaded from Hugging Face are subject to the license shown on their model card.