opendatalab/MinerU

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/opendatalab/MinerU.svg?style=card)](https://bestofgithub.dev/repo/opendatalab/MinerU)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/opendatalab/MinerU.svg)](https://bestofgithub.dev/repo/opendatalab/MinerU)

Loading README…

Type	Extensions
PDF	`.pdf`, including scanned PDFs and academic papers
Images	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.jp2`
Word	`.doc`, `.docx`
PowerPoint	`.ppt`, `.pptx`
Excel	`.xls`, `.xlsx`
Rich text	`.rtf`
OpenDocument	`.odt`, `.ods`, `.odp`
EPUB	`.epub`, parsed as a full document in OPF spine order with source internal links preserved
OFD	`.ofd`
HTML	`.html`, `.htm`, `.shtml`
MHTML web archive	`.mhtml`, `.mht`
CSV / TSV	`.csv`, `.tsv`

Tier	Chinese name	Quality and speed	Use for
`flash`	极速解析	Lowest quality; fastest	Discovery, preview, and indexing; never default final reading quality
`basic`	基础解析	Basic quality; moderate speed	Private local reading or lower-resource local parsing
`standard`	标准解析	Standard high quality; similar speed to `basic` on suitable hardware	Default for normal active reading and complex documents
`advanced`	高级解析	Standard quality on ordinary documents and better quality on difficult documents; slowest	Difficult documents and maximum-quality work when the user accepts a longer wait

Extra	Model engines installed	How to install
(base)	ONNX + llama.cpp	Already in `mineru` base module
`torch`	ONNX + PyTorch + llama.cpp	Install with `mineru[torch]` (Apple Silicon already installed this extra in base package.)
`full`	ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx	Install with `mineru[full]`

Tier	Model engines	Model download	Min RAM required	Accelerator
`basic`	ONNX	~0.8 GB	2GB	None (CPU works)
`basic`	PyTorch	~0.8 GB	8 GB	GPU/MPS recommended
`standard` / `advanced`	ONNX + llama.cpp	~2 GB	8 GB	CPU works, Vulkan recommended
`standard` / `advanced`	PyTorch + llama.cpp	~2 GB	16 GB	GPU/MPS required, 8 GB+ VRAM
`standard` / `advanced`	PyTorch + vLLM/lmdeploy/mlx	~3 GB	16 GB	GPU/MPS required, 8 GB+ VRAM

Hardware	Recommended startup tier	Model engines	Extra
MacOS with Apple Silicon	`standard`	PyTorch + llama.cpp	`torch` (already installed)
MacOS with Intel CPU	`basic`	ONNX	(base)
Linux/Windows with NVIDIA GPU and 8GB+ VRAM	`standard`	PyTorch + vLLM/lmdeploy	`full`
Linux/Windows with NVIDIA GPU and 4GB+ VRAM	`basic`	PyTorch	`torch`
Linux/Windows with other accelerator	(depends)	PyTorch / vLLM	install custom torch/vllm by yourself
Linux/Windows with modern iGPU	`standard`	ONNX + llama.cpp	(base)
Linux/Windows w/o modern accelerator	`basic`	ONNX	(base)

Variable	Meaning
`MINERU_HOME`	MinerU home, default `~/.mineru`
`MINERU_API_KEY`	API key for remote parsing when remote is explicitly allowed

Code	Meaning	Agent action
`server_not_running`	MinerU background service is unavailable	Run `mineru server start`, then retry once
`quality_tier_unavailable`	Normal reading quality is unavailable	Follow the Normal-Quality Recovery Gate; do not fall back automatically
`no_engine`	Requested tier is unavailable locally	Follow the Normal-Quality Recovery Gate; do not fall back automatically
`engine_unavailable`	Engine process unavailable	Retry if `retryable`; otherwise check `mineru server status`
`parse_server_unavailable`	Parsing service cannot be reached	Check `mineru server status`; do not switch privacy boundary
`tier_mismatch`	Requested tier unsupported	Ask user to choose a supported tier
`parse_failed`	MinerU could not parse the file	Report failure; suggest a different tier only if privacy rules allow
`parse_timeout`	Parse exceeded timeout	Retry with longer `--wait`, inspect status, or use lower tier if user accepts
`parse_oom`	Memory or VRAM exhausted	Suggest lower quality, smaller `--pages`, or remote only with permission
`remote_not_allowed`	Remote might be needed but was not authorized	Ask user whether uploading is acceptable; do not add `--remote` yourself
`invalid_api_key`	API key invalid	Ask user to set a valid key
`quota_exceeded`	Remote quota exhausted	Suggest waiting or using local
`rate_limit_exceeded`	Remote rate limit	Retry later if appropriate
`file_not_found`	Path or file id missing	Ask for correct path or run `mineru find`
`file_permission_denied`	Local file unreadable	Ask user to fix permissions
`file_type_unsupported`	Format unsupported	Report unsupported type
`file_encrypted`	Password-protected file	Ask user for an unlocked copy
`file_corrupted`	File cannot be read	Ask for a valid copy
`page_range_invalid`	Bad PDF `--pages` value, or `--pages` used with any non-PDF input	Correct the PDF range or omit it for full-document parsing
`parse_not_required`	The input is a directly readable text file	Read the source file directly; do not retry `mineru parse`
`not_cached` / `cache_miss`	Requested cached content does not exist	Run `mineru parse`

MinerU

Overview

MinerU 4.1

MinerU 4.0

Quick Start

In Agent Workflow

Install Manually

Python SDK

Agent Guide

MinerU

When To Use MinerU

Supported Inputs

Do Not

Agent Contract

Core Decision Tree

Common Workflows

First read from a file

Continue progressively

Read or inspect a known location

Search local library, then read

Installation And Setup

Upgrade An Existing Installation

Install with uv (preferred)

Install with pipx

Install with global pip

If No Supported Installer Is Available

After Installation

Privacy Rules

Telemetry

Quality Tiers

Model Engines with Extras

Server Rules

Local Parse Server

Inspect Local Hardware

Choose Extra

Choose Local Tier

Recommend and Ask

Configure Managed Parse Server

First Read From A File

Continue Reading

Read By Locator

Read Page Or Block Images

Search And Find

Inspect Status

Watch, Scan, And Local Library Maintenance

Reparse And Cache Control

Configuration

Remote API Usage

JSON Output

Error Recovery

Normal-Quality Recovery Gate

Answering Users With MinerU Output

Operating Rules

All Thanks To Our Contributors

License Information

Acknowledgments

Citation

Star History

Links

Install with `uv` (preferred)

Install with `pipx`

Install with global `pip`