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.2.3 / DocVortex 0.6.24. See compatibility.
Choose a route:
- Python or Node: install the published package and use
parse()for Markdown orrun()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: install from crates.io, or build from a prepared checkout for the exact pinned sources. The published crate carries the optional-feature dependency advisories listed in compatibility.
- Local conversion: CLI
--backend localsupports 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.5.0. Check the release guide for current package and release availability before installing a specific version.
See usage, compatibility,
SDK, and official HTTP API.
For a local Vulkan llama.cpp VLM server, see the Vulkan Compose guide.
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 from crates.io:
cargo install mineru --locked --features office,legacy-office
The published crate resolves its Office dependencies from crates.io, so the
office and legacy-office features pull dependency versions with open
advisories; read
compatibility
before enabling them. A default-feature build and local-inference are clean.
Alternatively build from a prepared source checkout. 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.92+ 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.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| mineru_rs-0.5.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for mineru_rs-0.5.0-cp39-abi3-win_amd64.whl |
| mineru_rs-0.5.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for mineru_rs-0.5.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| mineru_rs-0.5.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for mineru_rs-0.5.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| mineru_rs-0.5.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for mineru_rs-0.5.0-cp39-abi3-macosx_11_0_arm64.whl |
| mineru_rs-0.5.0-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for mineru_rs-0.5.0-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 55.2 MB
Release files / mineru_rs-0.5.0-cp39-abi3-win_amd64.whl
| Download URL | mineru_rs-0.5.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 10.3 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
601ba8aff674b812473932ed22e1ac3c9fc4b7a3fac912bca0887c4e2583d7f4
|
|
BLAKE2b-256 checksum How to use checksums |
e23fb29aa1382ce54c9c83ead08ebe2be2d0e635fe6b9603593c77fec562d3ca
|
| 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 Nov 19, 2026.
Transparency logRelease files / mineru_rs-0.5.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | mineru_rs-0.5.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 11.8 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
373b62630801dbf56c818f8a629df77eb161ae3532e62d9bd7e18666ecf0d0bd
|
|
BLAKE2b-256 checksum How to use checksums |
251b5f32c475e40559bed19ca85f4e0849a990e42a6c53ab83fbb7a714e9f29a
|
| 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 Nov 19, 2026.
Transparency logRelease files / mineru_rs-0.5.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | mineru_rs-0.5.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 11.4 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
309547f8a9c0ae8d9d3982deb42c749c38d338a8ffbbb783fef3ebb35e39e3f0
|
|
BLAKE2b-256 checksum How to use checksums |
38a00a6ae565c876f1d84fbb5039c503e02fba18794733b13580ecd62833c57c
|
| 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 Nov 19, 2026.
Transparency logRelease files / mineru_rs-0.5.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | mineru_rs-0.5.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 10.5 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a5faa7864b841bf9957d5819c55401a53c442ddeeef04e4261c07154f5a1dbe5
|
|
BLAKE2b-256 checksum How to use checksums |
e10c2eef9afe50bcb014d836ec03d01f568b23ac47e4d15c2a41cdb70b8c168c
|
| 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 Nov 19, 2026.
Transparency logRelease files / mineru_rs-0.5.0-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | mineru_rs-0.5.0-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 11.1 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
0f2ac018442138e81a0397419579059ac4b202acd11bd352293a28c1c79be03e
|
|
BLAKE2b-256 checksum How to use checksums |
3bfc5fdba3a709edbc54da72a8d0d026d7d88d71708ceab45776dee12d83e763
|
| 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 Nov 19, 2026.
Transparency logSecurity for mineru-rs 0.5.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.
Attestation for mineru_rs-0.5.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 Nov 19, 2026.
Transparency logA 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.