MinerU Rust

简体中文 | English

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-mistralrs backend 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:

Install the mineru command with Cargo, pip, or npm:

cargo install mineru            # Rust
pip install mineru-rs           # Python
npm install @alexsun-top/mineru # Node.js

Then parse a document:

mineru -p input.pdf -o out/

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):

cargo build --release --locked --features mistralrs --bin mineru-mistralrs

./target/release/mineru-mistralrs input.pdf --output output

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

cargo add mineru

use mineru::{RunOptions, run};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    run(RunOptions::new("input.pdf", "out/")).await?;
    Ok(())
}

Python

Wheels support CPython 3.9 and newer. Install with uv or pip:

uv add mineru-rs
# or: pip install mineru-rs

parse() returns the markdown string in memory; save it yourself:

import asyncio
from pathlib import Path

import mineru_rs


async def main() -> None:
    result = await mineru_rs.parse("input.pdf")
    await asyncio.to_thread(
        Path("out.md").write_text, result.markdown, encoding="utf-8"
    )


asyncio.run(main())

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:

pnpm add @alexsun-top/mineru
# 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

cargo install mineru
mineru --help

The package installs the mineru and mineru-api binaries. To also install the mineru-office-convert Office conversion helper, build with --features office:

cargo install mineru --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.

export MINERU_VL_SERVER="https://<server>"
export MINERU_VL_MODEL_NAME="<model-id>"
export MINERU_VL_API_KEY="<your-key>"

mineru-api --port 8000

Submit a document as an async task and fetch the result:

curl -X POST http://127.0.0.1:8000/tasks \
  -F "files=@input.pdf" -F "backend=vlm-http-client" -F "response_format_zip=true"
# poll the returned status_url, then download result_url

The mineru client can submit through a running server:

mineru -p input.pdf -o output --api-url http://127.0.0.1:8000

--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+):

  cargo install mineru
  cargo install mineru --features office   # also installs the Office helper
  

  The published crate intentionally does not include the local model backend; build mineru-mistralrs from source (below), use the CUDA image, or download a standalone binary. Note: cargo install mineru --features mistralrs would 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:

git clone https://github.com/agentsyaml/mineru-rs
cd mineru-rs
cargo build --release
./target/release/mineru --help

Build the optional local mineru-mistralrs backend:

cargo build --release --locked --features mistralrs --bin mineru-mistralrs

As a library in your own project: cargo add mineru.

Command-line usage

Options

The local mineru-mistralrs backend parses PDFs with these options:

The canonical mineru command reads the service address and model from the MINERU_VL_SERVER and MINERU_VL_MODEL_NAME environment variables:

export MINERU_VL_SERVER="https://<server>"
export MINERU_VL_MODEL_NAME="<model-id>"
export MINERU_VL_API_KEY="<your-key>"
mineru -p input.pdf -o output

Process pages 0–2 with the local backend, disabling formulas and image analysis:

mineru-mistralrs input.pdf --page-start 0 --page-end 2 \
  --no-formula --no-image-analysis --output output

Output

• mineru (remote) writes to output/ directly: document.md, document.json, middle.json, content_list.json, cropped assets/, and a layout preview {stem}_layout.pdf.
• mineru-mistralrs (local) writes MinerU official-shape output to output/<stem>/vlm/: {stem}.md, {stem}_middle.json, {stem}_model.json, {stem}_content_list.json, {stem}_content_list_v2.json, {stem}_layout.pdf, and images/.

{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:

--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:

The four 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:

mkdir -p output .hf-cache
docker run --rm --gpus all --user "$(id -u):$(id -g)" \
  -v "$(pwd):/work" -w /work \
  -e HF_HOME=/work/.hf-cache \
  ghcr.io/agentsyaml/mineru-rs-cuda:latest-sm80 \
  input.pdf --output output

For a different GPU, build your own image with your GPU's compute capability (for example, 89 for RTX 40-series):

docker build --platform linux/amd64 -f Dockerfile.cuda --build-arg CUDA_COMPUTE_CAP=89 -t mineru-rs-cuda .
docker run --rm --gpus all --user "$(id -u):$(id -g)" \
  -v "$(pwd):/work" -w /work \
  -e HF_HOME=/work/.hf-cache \
  mineru-rs-cuda input.pdf --output output

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.

Download, extract, and run:

curl -LO https://github.com/agentsyaml/mineru-rs/releases/latest/download/mineru-mistralrs-cpu-x86_64-unknown-linux-gnu.tar.gz
tar xzf mineru-mistralrs-cpu-x86_64-unknown-linux-gnu.tar.gz
./mineru-mistralrs input.pdf --output output

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

cargo build --release
cargo test

# local backend unit tests (the real-model test is ignored unless
# MINERU_VL_MODEL_DIR points at local weights)
cargo test --features mistralrs --lib

License

MIT OR Apache-2.0. Model weights downloaded from Hugging Face are subject to the license shown on their model card.