Skip to main content

MinerU Rust

中文 | English

Parse PDF, image, and Office documents into Markdown with a Rust library, CLI, and HTTP API server. PDF rendering is implemented in Rust. The legacy CLI/API and Python/Node run/parse paths use a remote MinerU-compatible VLM (MinerU 3.4.5 protocol baseline); rich parsing also includes Rust-native CSV/TSV, while other formats use a separate Python worker. The checked-in worker contract is MinerU 4.0.12 / DocVortex 0.5.16; the latest DocVortex 0.6.0 reference has model-free smoke coverage only. See compatibility.

Choose a route:

  • Python or Node: install the published package and use parse() for Markdown or run() for the complete output tree. See the language examples.
  • Rich official SDK: use the Rust, Python, or Node SDK; CSV/TSV parse in Rust and other formats use a separately prepared worker. See the SDK guide for its runtime contract.
  • Rust CLI / API server: build from a prepared checkout. The crate is not available from crates.io because root workspace patches do not reach consumers.
  • Local conversion: CLI --backend local supports clean text PDFs and selected legacy formats through the bundled Rust helper. It produces Markdown only, without layout JSON or a VLM call.

This checkout targets 0.4.0. Check the release guide for current package and release availability before installing a specific version.

See usage, compatibility, SDK, and official HTTP API.

Quickstart

Install Python (CPython 3.9+) or Node.js 18+, then configure a MinerU-compatible VLM endpoint. A general-purpose chat endpoint is not sufficient.

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
export MINERU_VL_SERVER="https://host/v1"
export MINERU_VL_MODEL_NAME="model-id"
# If required, enter the key without echoing it or saving it in shell history:
read -rs -p "VLM API key: " MINERU_VL_API_KEY; export MINERU_VL_API_KEY
printf '\n'

For the Python CLI, install the published wheel and run:

python -m pip install mineru-rs
mineru-rs -p input.pdf -o out/

For Node.js, check the registry version and invoke its mineru-rs bin:

version="$(npm view @alexsun-top/mineru version)"
npx --yes --package="@alexsun-top/mineru@$version" -- mineru-rs -p input.pdf -o out/

The full output tree is written to out/; use parse() when you only need Markdown in memory, or run() to write that tree from application code.

Prefer the MINERU_VL_API_KEY environment variable over --api-key so the key does not end up in shell history.

Python

Install mineru-rs with uv or pip on CPython 3.9+. Use parse() for Markdown or run() for the complete output tree. The published wheel does not include the Rust Office conversion helper. See the uv example and SDK guide.

Node.js

Install @alexsun-top/mineru with npm or pnpm on Node.js 18+. Use parse() for Markdown or run() for the complete output tree. The published package does not include the Rust Office conversion helper. See the pnpm example and SDK guide.

CLI and API server

Install Rust CLI binaries from a prepared source checkout as shown below.

A source build produces the mineru, mineru-api, and mineru-office-convert binaries. The conversion capabilities are opt-in features. Run the preparation commands under Build from source first; they are required before any Cargo command in this checkout.

cargo install --path . --locked --features office          # docx/pptx/xlsx → PDF + VLM
cargo install --path . --locked --features legacy-office   # legacy → bounded text PDF + VLM; local/native PDF → bundled-helper Markdown
cargo install --path . --locked --features office,legacy-office

The legacy-office feature adds isolated local Markdown conversion for selected legacy formats and clean text PDFs. It is not a local inference backend; uncertain PDFs fail rather than generating layout output. See usage and compatibility for supported inputs and backend details.

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>"
# If required, enter the key without echoing it or saving it in shell history:
read -rs -p "VLM API key: " MINERU_VL_API_KEY; export MINERU_VL_API_KEY
printf '\n'

mineru-api --port 8000

Keep the server bound to loopback or behind an authenticated reverse proxy: the task API has no built-in authentication or task ownership. See the usage guide for endpoints and complete options.

Build from source

Requires Rust 1.89+ and Python 3.9+. Prepare dependencies before any Cargo command in this checkout:

git clone https://github.com/agentsyaml/mineru-rs
cd mineru-rs
python3 tools/deps/prepare_office.py prepare
python3 tools/deps/prepare_office.py verify
cargo build --release --locked --features office,legacy-office
./target/release/mineru --help

prepare fetches hash-pinned source archives; verify checks the generated .deps/office-xml041/ tree offline. Do not edit that generated tree by hand. Install with cargo install --path . --locked --features office,legacy-office.

Examples

License

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

Metadata

Release files for mineru-rs 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for mineru-rs 0.4.0
File Actions
mineru_rs-0.4.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for mineru_rs-0.4.0-cp39-abi3-win_amd64.whl
mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
mineru_rs-0.4.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for mineru_rs-0.4.0-cp39-abi3-macosx_11_0_arm64.whl
mineru_rs-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for mineru_rs-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 56.3 MB

Release files / mineru_rs-0.4.0-cp39-abi3-win_amd64.whl

Download URL mineru_rs-0.4.0-cp39-abi3-win_amd64.whl
Size 10.4 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
0f24e255b912237fc9bd5f03c5212cdf04d70f56bdba5060d3176537255a80f4
BLAKE2b-256 checksum
How to use checksums
a10bd11a731b0cd66f9292e58e1cbfa27e3692c8b690f9a586b4f85083e32d2c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 12.3 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
eb307931f542e17243647845fe7041fde68ede97ea522207dcda1a651368600f
BLAKE2b-256 checksum
How to use checksums
6ddddb4e9565a84f5555251b186c33cc39c5c2e82c8548fc2e5f0d03ed6e1186
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL mineru_rs-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 11.6 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
ce0f289c21e2574f384c1d8f649d7f1818964a70addd76e78dfe095281cbefe2
BLAKE2b-256 checksum
How to use checksums
e758b8df84e3aebb65322d389a8ae3c0fabf2e5985494e4fe5b6dfeb77950a4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / mineru_rs-0.4.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL mineru_rs-0.4.0-cp39-abi3-macosx_11_0_arm64.whl
Size 10.6 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
66b7e7c47bb21c4a90eec6acbde5a98d091c6dc37aaf8055cb49407a55179990
BLAKE2b-256 checksum
How to use checksums
ad549db978d9f35d8dec93cebf35de3143de8c6fe2317dc8bd89d2ac295ce8d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / mineru_rs-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl

Download URL mineru_rs-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 11.3 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
a28829b989bf4600bc22e708b3be930a960b9ed049d4c3fc3a9c296d8d1e7043
BLAKE2b-256 checksum
How to use checksums
74281ede21787d222c50a9f843f0f509321ea03ac71cbc535dc4831edf87f0f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for mineru-rs 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for mineru_rs-0.4.0-cp39-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page