Who MinerU is for#
AI engineers building RAG knowledge bases
MinerU converts local document libraries into LLM-ready content with stable per-block locators that allow retrieval systems to cite exact source positions. The document library API indexes parsed results and supports search without re-parsing files already in the cache.
Skip if:
Your source documents are already in plain text or structured JSON formats. MinerU's value is in converting unstructured files; if your pipeline already has clean text, a lighter extraction layer is simpler.
Developer teams building document-aware agents
Agents can call `mineru parse --json` to read a document page by page using continuation locators, which avoids loading large files into context. The V1 HTTP API and Python SDK both support the document library, making it usable from any language that can call HTTP.
Skip if:
Your agent needs to process documents in formats MinerU does not support, or the documents are served by a remote URL that requires browser authentication. MinerU reads local files and explicitly configured remote sources.
Researchers parsing academic PDFs and papers
The Standard and Advanced tiers handle academic paper layouts: multi-column text, embedded formulas, figures with captions, and reference lists. Output in Markdown, LaTeX, or Structured Content makes it usable for downstream analysis, translation, or re-typesetting.
Skip if:
You need only plain abstract text from papers and speed matters more than formula or table fidelity. Flash tier or a simpler PDF-to-text tool may be faster for high-volume abstract scraping.
Enterprise teams parsing mixed document libraries
MinerU processes twelve-plus formats in one unified pipeline without separate tools for Word, Excel, and PDF. Batch conversion via `mineru-kit` and stateless API calls make it compatible with existing ETL workflows. The local-first model keeps confidential documents off third-party servers.
Skip if:
Your organization has no Python runtime environment and needs a managed API with no infrastructure setup. In that case, a paid service like LlamaParse or Reducto requires less operational overhead.
The problem it solves#
Converting documents into usable text for AI systems is harder than it looks. PDFs contain embedded fonts, complex column layouts, tables that span pages, mathematical formulas, and scanned raster images mixed with native text. Generic parsers either flatten everything into a single text stream or fail entirely on scanned pages. OCR libraries work on images but lose structure, table cells bleed together, and formula rendering produces nonsense strings.
The challenge compounds for teams running document agents or RAG pipelines. Agents need to continue reading from a specific page or block without reprocessing the whole file. Citation systems need stable locators that survive document updates. Batch pipelines need consistent output quality across thousands of mixed-format files. Most teams end up stitching together multiple single-purpose libraries, paying per-page fees to hosted APIs, or shipping fragile custom preprocessing scripts that break when document formats shift.
How it solves it#
Four parsing quality tiers
Flash handles fast previews and indexing; Basic adds OCR and model-based parsing; Standard and Advanced handle demanding layouts, complex tables, and accuracy-sensitive content. Each tier trades speed for quality, and different tiers can be applied to different files in the same pipeline.
Twelve-plus input formats
Accepts PDF, images (PNG, JPG, WebP, GIF, BMP, TIFF, JP2), DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP, EPUB, OFD, HTML/MHTML, and CSV/TSV. PDF and images support all four tiers; Office and HTML formats use Flash native parsing locally.
Nine structured rendering targets
One document model maps to Markdown, HTML, LaTeX, DOCX, EPUB, PDF, Structured Content, and Content List V1/V2. The same parse result can be exported to multiple formats without reprocessing, which simplifies multi-consumer pipelines.
Document library with stable locators
The document library caches parse results, indexes content for search, and returns page- and block-level locators in the form `doc:{short_id}/tier:{tier}/page:{n}/block:{n}`. Agents can continue reading from a specific block across multiple calls without reloading the full document.
Independent model configuration
Small models run ONNX or Torch inference; the VLM can run via llama.cpp, vLLM, or LMDeploy. The default install uses ONNX CPU and llama.cpp in Vulkan mode for broad hardware compatibility. NVIDIA GPU support is available with `mineru[full]`.
Python SDK, HTTP API, and Gradio WebUI
`DoclibClient` drives the document library from Python with methods for parsing, search, page continuation, and locator retrieval. The V1 HTTP API covers stateless batch conversion. A Gradio WebUI is included for browser-based access without writing code.
Strengths and trade-offs#
Strengths
- Local-first processing with no default data uploadDocuments are not uploaded to any external service unless explicitly configured for remote parsing. All parsing runs on your own infrastructure, which matters for confidential documents, regulated data, and air-gapped environments.
- 81,000+ stars and actively maintainedThe repository has over 81,700 stars and 6,700 forks, with the last push on 14 October 2026. OpenDataLab has published technical reports on arXiv (MinerU, MinerU 2.5, MinerU 2.5 Pro) documenting the parsing models' design and benchmarks.
- No per-page API costsUnlike LlamaParse and Reducto, which charge per page or per document, MinerU's self-hosted path has no per-call billing. The cost model is compute, not consumption, which makes it cheaper at scale for high-volume document pipelines.
- Stable locators for agentic workflowsThe `doc:{short_id}/tier:{tier}/page:{n}/block:{n}` locator format lets agents cite and resume from specific positions within a document across multiple API calls. This is a documented design choice for agent workflows, not an afterthought.
Trade-offs
- -Fair-code license with commercial thresholdsThe license embeds Apache 2.0 terms but adds a commercial threshold. Organizations exceeding 100 million monthly active users or USD 20 million monthly revenue must obtain a separate commercial license. If you build a hosted service on top of MinerU for third parties, you must display attribution; omitting it terminates all license rights. This makes MinerU non-OSI-compliant and unsuitable for products that cannot meet the attribution or threshold requirements.
- -Full throughput requires an NVIDIA GPUThe default install runs ONNX CPU inference, which is sufficient for most workloads. Standard and Advanced tiers at high throughput benefit significantly from a CUDA-capable NVIDIA GPU and the `mineru[full]` install. Non-NVIDIA accelerated inference requires manual torch and vLLM/LMDeploy setup.
- -Non-NVIDIA Docker deployment pending updateAs of the MinerU 4.0 release, Docker deployment for non-NVIDIA devices is listed as pending an update. GPU Docker images are available; non-GPU Docker users should check the legacy platform guides until updated images are published.
MinerU vs alternatives#
MinerU vs LlamaParse
LlamaParse is LlamaIndex's managed document parsing API, designed to feed LlamaIndex's RAG pipelines. It requires no infrastructure and returns clean markdown or JSON from PDFs in a single API call, but all documents pass through their servers and pricing scales with page volume.
| Feature | MinerU | LlamaParse |
|---|---|---|
| Self-hosting | Yes | No |
| Data residency | Local by default | Cloud (LlamaCloud) |
| Parsing tiers | 4 (Flash to Advanced) | Tiered plans |
| License | Apache 2.0 + thresholds | Proprietary (free tier available) |
| Python SDK | Yes | Yes |
| Per-page pricing | No (compute cost only) | Yes |
MinerU is the better choice when documents contain sensitive data that cannot leave your infrastructure, when document volume is high enough that per-page API costs add up, or when you need to customize the parsing pipeline at the model level. LlamaParse is the easier option when you are already using LlamaIndex and want a zero-ops extraction layer with no infrastructure to manage.
MinerU vs Reducto
Reducto is a document parsing API optimized for enterprise document types with a focus on tables and structured extraction. Like LlamaParse, it is a managed cloud service with no self-hosting path.
| Feature | MinerU | Reducto |
|---|---|---|
| Self-hosting | Yes | No |
| Input formats | 12+ formats | PDF and images |
| Output formats | 9 targets | JSON/Markdown |
| License | Apache 2.0 + thresholds | Proprietary |
| Agent integration | Python SDK + locators | REST API |
MinerU covers more input formats and supports Office documents natively, which Reducto does not. Reducto's managed API is worth considering when extraction accuracy on enterprise PDF tables is the primary concern and you prefer outsourcing infrastructure. MinerU's local-first model and format breadth make it the stronger default for teams that need to own their pipeline.
Quick start#
Install MinerU in a Python 3.10+ virtual environment using the uv package manager.
```bash
pip install uv
uv venv .mineru --python 3.12
source .mineru/bin/activate
uv pip install -U "mineru>=4.0,<5"
mineru-kit parse document.pdf -o output.md --tier standard
```What it's built on#
- Languages
- JavaScriptPython
- Frameworks
- FastAPI
FAQ#
Is MinerU free to use?
Yes for self-hosted use. The self-hosted path has no per-call charges; you pay for compute, not API calls. The license permits self-hosting and internal commercial use without a fee unless your organization exceeds 100 million monthly active users or USD 20 million monthly revenue. There is also a free web demo at mineru.net.
Does MinerU upload my documents to external servers?
No, not by default. Documents are processed locally and are not sent to any external service unless you explicitly configure remote parsing. This makes MinerU suitable for processing confidential, regulated, or proprietary documents.
What document formats does MinerU support?
MinerU supports PDF, images (PNG, JPG, WebP, GIF, BMP, TIFF, JP2), DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP, EPUB, OFD, HTML/MHTML, and CSV/TSV. PDF and images support all four parsing quality tiers; Office, HTML, and CSV files use local Flash native parsing.
How does MinerU compare to LlamaParse?
LlamaParse is a managed cloud API; MinerU runs on your own infrastructure. LlamaParse requires no setup but charges per page and sends documents to its servers. MinerU takes more work to install but has no per-page cost and keeps documents local. For teams with strict data residency requirements or high document volumes, MinerU is usually the better fit.
Can MinerU handle scanned PDFs?
Yes. The Basic tier adds OCR model-based parsing for scanned documents and images. Standard and Advanced tiers extend this with better layout understanding for documents with complex column structures, tables, and embedded formulas.
Similar open-source tools#
Marker
Convert documents to clean markdown and JSON with open source AI.
Unstructured
Document parsing and ETL for LLMs, RAG pipelines, and AI agents.
pdf-inspector
Rust-powered PDF parser with smart OCR routing for AI pipelines
Bifrost
Open-source AI gateway with 23+ providers, failover, and MCP support.
FckSignups
Open-source tools that work instantly, no signup required
Switchyard
LLM proxy with API translation and multi-backend routing