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) — run the MinerU Qwen2-VL model with the
mineru-mistralrsbackend on CPU or NVIDIA CUDA. The weights (~2.3 GB) can be downloaded automatically on first use.
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 output/ 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: parse with the model on your machine
Build the local backend and run it (CPU):
By default the first run downloads the fixed model
opendatalab/MinerU2.5-2509-1.2B (~2.3 GB) into the Hugging Face cache, then
reuses it. Pass --model-path /path/to/model to use a local model directory
instead, or --allow-download=false to forbid downloading (then --model-path
is required). Results are written to output/<stem>/vlm/ in MinerU's official
output shape. See Local model settings,
Docker for the CUDA image, and
Standalone binaries for prebuilt executables.
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.
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.
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
Prebuilt
-
Standalone binaries — CPU, CUDA, and Metal builds of
mineru-mistralrs, see Standalone binaries. -
Docker — CUDA image, see Docker.
-
crates.io — install the remote-only command-line tools (requires Rust 1.89+):
The published crate intentionally does not include the local model backend; build
mineru-mistralrsfrom source (below), use the CUDA image, or download a standalone binary. Note:cargo install mineru --features mistralrswould compile but silently use the unpatched upstream core — do not use that flag on the published crate. -
Python —
pip install mineru-rs(CPython 3.9+). -
Node.js —
npm install @alexsun-top/mineru(Node.js 18+).
Build from source
Clone the repository and build the remote CLI/API tools:
Build the optional local mineru-mistralrs backend:
As a library in your own project: cargo add mineru.
Command-line usage
Options
The local mineru-mistralrs backend parses PDFs with these options:
| Option | Default | Description |
|---|---|---|
input |
required | PDF to parse (positional argument). |
--output <dir> |
output |
Directory for the results. |
--page-start <n> |
0 | First page to parse (zero-based). |
--page-end <n> |
last page | Last page to parse (inclusive). |
--no-formula |
off | Skip formula recognition. |
--no-table |
off | Skip table recognition. |
--no-image-analysis |
off | Skip image/figure analysis. |
The canonical mineru command reads the service address and model from the
MINERU_VL_SERVER and MINERU_VL_MODEL_NAME environment variables:
Process pages 0–2 with the local backend, disabling formulas and image analysis:
Output
mineru(remote) writes tooutput/directly:document.md,document.json,middle.json,content_list.json, croppedassets/, and a layout preview{stem}_layout.pdf.mineru-mistralrs(local) writes MinerU official-shape output tooutput/<stem>/vlm/:{stem}.md,{stem}_middle.json,{stem}_model.json,{stem}_content_list.json,{stem}_content_list_v2.json,{stem}_layout.pdf, andimages/.
{stem} is the input filename without its extension.
API server
mineru-api is the HTTP API server: it accepts documents, calls the
configured VLM, and returns result archives. It performs no local inference.
See CLI and API server for the API-mode submission
flow.
Local model and Hugging Face settings
The local mineru-mistralrs backend loads a Qwen2-VL MinerU model from one of
two sources, controlled by CLI options:
| Option | Default | Effect |
|---|---|---|
--model-path <dir> |
none | Use a local model directory. Always takes priority and never falls back to downloading. |
--allow-download[=<bool>] |
true |
Download opendatalab/MinerU2.5-2509-1.2B (~2.3 GB) on first use into the Hugging Face cache when --model-path is absent. |
--allow-download accepts an explicit boolean value
(--allow-download=false disables downloading; then --model-path is
required). The legacy MINERU_VL_MODEL_DIR and MINERU_VL_AUTO_DOWNLOAD
environment variables are still honored, with the CLI options taking
precedence.
A local model directory must contain config.json (Qwen2-VL architecture),
tokenizer.json, preprocessor_config.json, and model.safetensors; it is
validated before anything else happens.
Hugging Face settings that also apply to downloads:
| Variable | Effect |
|---|---|
HF_HOME |
Where the model cache lives. |
HF_TOKEN |
Hugging Face access token, for gated or private repositories. |
HF_HUB_OFFLINE=1 |
Force fully offline operation from the local cache. |
The four 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. |
mineru-mistralrs |
Local PDF parsing with the Qwen2-VL MinerU model; built from source with --features mistralrs, or shipped in the CUDA image and standalone binaries. |
Docker
CUDA image (local inference)
ghcr.io/agentsyaml/mineru-rs-cuda:latest-sm80 ships mineru-mistralrs for
local parsing on NVIDIA GPUs. The tag targets compute capability 8.0
(Ampere-class) GPUs; it is not a universal all-GPU image. The image ENTRYPOINT
is mineru-mistralrs, so arguments after the image name go straight to the
CLI:
For a different GPU, build your own image with your GPU's compute capability
(for example, 89 for RTX 40-series):
The .hf-cache bind mount keeps downloaded weights across runs. You may use a
named volume mounted at /data instead; the CUDA image defaults HF_HOME to
that path.
There is no CPU Docker image; the CPU backend ships as a standalone binary instead (see below).
Standalone binaries
Prebuilt mineru-mistralrs executables are attached to every GitHub Release
as mineru-mistralrs-{variant}-{rust-target}.tar.gz; each tarball contains the
single executable and needs no npm or Python wrapper.
| Variant | Rust target | Platform | Notes |
|---|---|---|---|
cpu |
x86_64-unknown-linux-gnu |
Linux, amd64 | CPU inference. |
cpu |
aarch64-unknown-linux-gnu |
Linux, arm64 | CPU inference. |
cpu |
aarch64-apple-darwin |
macOS, Apple Silicon | CPU inference. |
metal |
aarch64-apple-darwin |
macOS, Apple Silicon | Metal-accelerated inference; requires macOS 13+ and Apple Silicon. |
cuda |
x86_64-unknown-linux-gnu |
Linux, amd64 | CUDA inference; requires an NVIDIA driver (libcuda.so.1) and a compute capability 8.0 (Ampere-class) or newer GPU. |
Download, extract, and run:
Each Release also attaches a SHA256SUMS file covering its artifacts, so the
tarball can be verified against it before use.
Examples
- examples/python-uv — Python with
uv - examples/node-pnpm — Node.js with
pnpm
Build and test
# local backend unit tests (the real-model test is ignored unless
# MINERU_VL_MODEL_DIR points at local weights)
License
MIT OR Apache-2.0. Model weights downloaded from Hugging Face are subject to the license shown on their model card.