[](https://github.com/opendatalab/MinerU)
[](https://github.com/opendatalab/MinerU)
[](https://github.com/opendatalab/MinerU/issues)
[](https://github.com/opendatalab/MinerU/issues)
[](https://pypi.org/project/mineru/)
[](https://pypi.org/project/mineru/)
[](https://pepy.tech/project/mineru)
[](https://pepy.tech/project/mineru)
[](https://mineru.net/OpenSourceTools/Extractor?source=github)
[](https://huggingface.co/spaces/opendatalab/MinerU)
[](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
[](https://colab.research.google.com/gist/myhloli/a3cb16570ab3cfeadf9d8f0ac91b4fca/mineru_demo.ipynb)
[](https://arxiv.org/abs/2409.18839)
[](https://arxiv.org/abs/2509.22186)
[](https://arxiv.org/abs/2604.04771)
[](https://deepwiki.com/opendatalab/MinerU)
[English](https://github.com/opendatalab/MinerU/blob/HEAD/README.md) | [简体中文](https://github.com/opendatalab/MinerU/blob/HEAD/README_zh-CN.md)
👋 join us on Discord and WeChat
# MinerU 4.0
MinerU 4.0 brings document parsing, a local document library, and service tools into one workflow for document conversion, application integration, and agent reading.
- **Four parsing tiers**: Flash for fast previews and indexing, Basic for OCR and model-based parsing, and Standard / Advanced for more demanding layouts and quality requirements.
- **Multiple input formats**: PDF, images, DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP, EPUB, OFD, HTML/MHTML, and CSV/TSV. [DocVortex](https://github.com/myhloli/docvortex) provides native document parsing.
- **Document library and agent reading**: discover files, cache results, search content, continue by page or block, and preserve stable citation locators.
- **Independent model configuration**: ONNX or Torch for small models; llama.cpp, vLLM, or LMDeploy for the VLM.
- **Unified tools**: Python SDK, V1 API, stateless batch conversion, multi-service Router, and a Gradio-based WebUI.
- **Structured results and rendering**: one document model supports nine rendering targets: Markdown, HTML, LaTeX, DOCX, EPUB, PDF, Structured Content, and Content List V1/V2. Each CLI/API exposes its own subset of exports; see [Output Formats and Result Contract](https://opendatalab.github.io/MinerU/reference/output_files/).
PDF and images support all four tiers. Office, OpenDocument, EPUB, OFD, HTML/MHTML, and CSV/TSV use local Flash native parsing. Plain text is read directly rather than parsed. Documents are not automatically uploaded to the official service; remote parsing requires explicit configuration.
## Quick Start
### In Agent Workflow
You can install the `mineru` skill, and let agent install MinerU for you. Copy the following message and send it to your agent:
```text
Install or update the global `mineru` skill. First, run `npx skills add opendatalab/MinerU --skill mineru --global --yes`. If `npx` is unavailable, fetch https://gcore.jsdelivr.net/gh/opendatalab/MinerU/skills/mineru/SKILL.md, use its content as `mineru/SKILL.md`, and save it under the appropriate global skills directory for the current agent, not in the current project. Also check both global and project-level skills for other installed skills whose names contain `mineru`. Report any matches and ask before removing them. If global memory is available, record this preference there: "Whenever a PDF, image, or Office document needs to be read or parsed, prefer the `mineru` Skill." Do not write this preference to the current project.
```
### Install Manually
Python `>=3.10,<3.15`. Install MinerU 4.0 stable in a virtual environment:
```bash
pip install uv
uv venv .mineru --python 3.12
# Linux/macOS
source .mineru/bin/activate
# Windows (PowerShell)
.\.mineru\Scripts\Activate.ps1
```
```bash
uv pip install -U "mineru>=4.0,<5"
mineru-kit parse document.pdf -o document.md --tier standard
mineru-kit webui
```
### Python SDK
`DoclibClient` drives the local document library from Python. Start the server first (`mineru server start`), then:
```python
import time
from mineru import DoclibClient
from mineru.doclib import ParseRequest
client = DoclibClient()
submit = client.ensure_parse(ParseRequest(path="paper.pdf", tier="standard"))
# ensure_parse returns immediately; poll the parse tasks it created.
for parse_id in submit.wait_parse_ids:
parse = client.get_parse(parse_id)
while parse.status in ("pending", "parsing"):
time.sleep(1)
parse = client.get_parse(parse_id)
if parse.status != "done":
raise RuntimeError(f"parse {parse_id} ended as {parse.status}: {parse.error_code} {parse.error_msg}")
content = client.read_content(f"doc:{submit.short_id}/tier:standard/page:1")
print(content.content)
```
`DoclibClient` also covers search, watched directories, locators for
page/block continuation, and result invalidation — see
`help(DoclibClient)` or the [SDK and API guide](https://opendatalab.github.io/MinerU/usage/sdk_api/).
The default install works out of the box: small models run ONNX CPU inference and the VLM runs llama.cpp in Vulkan mode, which offers good compatibility on the vast majority of devices. If the device has an NVIDIA GPU, install `mineru[full]>=4.0` for the best throughput. Note that on Windows the GPU build of torch must be installed separately, while on macOS the default install is already the best-throughput package and `[full]` is not needed. On other non-NVIDIA devices, you need to install an accelerated build of torch plus vllm/lmdeploy yourself to get the best inference speed and throughput.
For the document library and agent reading, use `mineru parse document.pdf --json`. It defaults to the first 10 PDF pages; continue with returned locators. Stateless `mineru-kit parse` defaults to all pages.
[Installation](https://opendatalab.github.io/MinerU/quick_start/) · [Tiers and runtimes](https://opendatalab.github.io/MinerU/usage/tiers/) · [SDK and API](https://opendatalab.github.io/MinerU/usage/sdk_api/) · [Docker deployment](https://opendatalab.github.io/MinerU/quick_start/docker_deployment/) · [3.x → 4.0 migration](https://opendatalab.github.io/MinerU/reference/migration_4/) · [Release history](https://opendatalab.github.io/MinerU/reference/changelog/)
> Docker deployment for non-NVIDIA devices is pending an update; see the [legacy platform guides](https://opendatalab.github.io/MinerU/usage/compatibility/) in the meantime.
# Agent Guide