MinerU: The Open Source Document Parsing Engine That Fixes the Foundation of Every Broken RAG System

There is a common pattern in teams that build retrieval-augmented generation systems and find that their answers are inconsistent, incomplete, or confidently wrong. The team investigates the embedding model. The team adjusts the chunking strategy. The team fine-tunes the retrieval parameters. The team evaluates reranking approaches. Weeks pass. The answers remain unreliable. Eventually, someone looks at what the documents actually look like after the parsing step, and the source of the problem becomes immediately clear.

The documents are a mess. Multi-column layouts have been flattened into a single stream with columns merged in the wrong order. Tables have been converted to unformatted text where row and column relationships are entirely lost. Mathematical equations appear as garbled Unicode. Images have been dropped silently. Section headings are indistinguishable from body text. The semantic structure of the original document, the structure that makes its content intelligible, has been destroyed by the parser before any retrieval algorithm ever had a chance to work with it.

Retrieval algorithms cannot recover structure that was destroyed upstream. A vector similarity search over semantically incoherent chunks will produce semantically incoherent results, regardless of how sophisticated the retrieval architecture is. The quality of a RAG system is bounded above by the quality of its document parsing step. If that step is poor, no amount of engineering downstream can fully compensate.

MinerU is an open source document parsing engine, now licensed under a custom license based on Apache 2.0, that treats high-fidelity structure preservation as a first-class requirement rather than an afterthought. With more than 72,000 stars on GitHub, it has become one of the most adopted tools in the developer community for converting complex, real-world documents into clean, machine-readable formats that downstream AI systems can actually work with.

What MinerU Produces and Why It Matters

The output of a document parser should not be evaluated only by whether it extracted the text. It should be evaluated by whether it preserved the information architecture of the original document in a way that makes that information retrievable and usable.

MinerU converts PDF files, images, DOCX files, PPTX presentations, and XLSX spreadsheets into Markdown and JSON formats that maintain the structural relationships present in the original documents. Headers remain headers. Paragraphs remain intact and in their correct reading order. Tables are converted to HTML format that preserves row and column structure, not flattened text where the cell relationships are lost. Mathematical formulas are converted to LaTeX format that preserves their mathematical structure and can be rendered or processed downstream. Images are extracted along with their captions and descriptions. Lists maintain their hierarchy. Multi-column layouts are handled so that text flows in the correct reading sequence rather than column-by-column or mixed.

This structural fidelity is what makes MinerU valuable for RAG system construction specifically. When documents are parsed with structure preserved, chunks can be formed around meaningful semantic units: a complete paragraph, a full table with its headers, a section with its heading intact. When structure is lost at the parsing stage, chunks are arbitrary slices of a flattened stream that bear no relationship to the semantic boundaries of the original content.

For enterprise knowledge bases built on internal documentation, technical reports, research papers, legal documents, and financial filings, the difference between structured and unstructured parsing output is the difference between a knowledge base that answers questions reliably and one that consistently misses context or retrieves fragments that lack meaning without the surrounding structure.

The Three Parsing Backends and When to Use Each

MinerU provides three distinct parsing backends, each optimized for different hardware environments and accuracy requirements.

The pipeline backend is designed for broad compatibility and can run in pure CPU environments without any GPU requirement. It achieves an OmniDocBench v1.6 end-to-end evaluation score of 86.47 and requires a minimum of 4 GB of VRAM when GPU acceleration is used, though it runs entirely on CPU as well. This backend is well-suited for deployment environments where GPU resources are unavailable or where compatibility across diverse hardware is more important than achieving maximum accuracy. The recent 3.4 release upgraded the OCR model in this backend to PP-OCRv6, improving OCR accuracy by approximately 11 percent and increasing OCR processing speed by approximately 100 percent through pipeline optimization.

The hybrid backend combines the pipeline approach with a vision language model to achieve substantially higher accuracy. With the high effort level, it reaches 95.39 on OmniDocBench v1.6, representing a significant improvement over the pipeline-only approach. The 3.3 release introduced a medium effort level that reduces this score by only 0.13 points while delivering parsing speed improvements of 35 to 220 percent across different platforms and scenarios. Linux text PDF scenarios run approximately 80 percent faster at medium effort. Windows text PDF scenarios run approximately 90 percent faster. macOS text PDF scenarios run approximately 220 percent faster. The default hybrid backend configuration now uses medium effort, making the typical document processing workflow substantially faster without meaningful accuracy loss.

The VLM backend and the HTTP client variants connect to OpenAI-compatible inference servers, either locally deployed through frameworks like vLLM, SGLang, or LMDeploy, or through remote model services. This configuration achieves accuracy comparable to the hybrid backend at high effort while offloading the compute requirements to external infrastructure. This path is appropriate for teams that already operate model serving infrastructure and want to use it for document parsing at scale.

Installation and Getting Started

Installation through pip or uv is the recommended path for most users:

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

The mineru[all] package includes all core features and is compatible with Windows, Linux, and macOS. Python versions 3.10 through 3.13 are supported, with the exception that Windows does not support Python 3.13 due to a dependency limitation with the ray library on that platform. macOS requires version 14.0 or later.

For users who prefer to install from source:

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

Docker deployment is available for Linux environments and Windows with WSL2 support, providing a pre-configured environment that resolves compatibility concerns without requiring manual dependency management.

Running a basic document parse from the command line requires a single command:

mineru -p <input_path> -o <output_path>

For environments without GPU acceleration, specifying the pipeline backend explicitly runs the parser entirely on CPU:

mineru -p <input_path> -o <output_path> -b pipeline

The input path can be a single file or a directory containing multiple documents. The output directory will contain the parsed Markdown files, extracted images, table HTML files, formula LaTeX files, and JSON output with reading-order sorting. Visualization outputs showing layout analysis and span detection are also available for quality verification.

The OCR Capabilities and Multilingual Support

Document parsing for enterprise use cannot be limited to cleanly typeset digital PDF files. A significant proportion of enterprise document collections include scanned documents, documents produced from older systems with imperfect digital structure, handwritten annotations, seal text, vertical text, and documents in languages other than English.

MinerU automatically detects scanned PDFs and activates OCR processing for them, removing the requirement for manual preprocessing or format detection. The OCR system supports 109 languages, covering the majority of languages encountered in global enterprise document collections. The 3.3 release upgraded the VLM model to MinerU2.5-Pro-2605–1.2B, which added native multilingual OCR support, reducing the need for explicit language parameter configuration and improving out-of-the-box usability for multilingual documents.

The 3.4 release simplified the language configuration further by routing Japanese, Traditional Chinese, English, and Latin documents to the optimized Chinese OCR model, which handles these scripts with higher accuracy than separate specialized models. This consolidation reduces configuration complexity while improving accuracy.

Seal text recognition handles the circular and irregular text that appears on official stamps in many business and legal documents, which is content that standard OCR approaches frequently fail on. Vertical text support handles the vertical text orientation used in traditional East Asian document formats. Interline formula numbering recognition handles the numbered equation format common in scientific and mathematical documents.

Complex Layout Handling for Enterprise Documents

The document types that matter most for enterprise AI systems are also the most structurally complex. Annual reports combine prose, financial tables, charts, and image captions in multi-column layouts. Research papers combine narrative text, mathematical notation, figures, tables, and references in formats designed for print rather than machine processing. Technical specifications mix hierarchical text structures with diagrams, code blocks, and specification tables. Legal documents contain complex hierarchical numbering, cross-references, and embedded tables.

MinerU’s approach to these documents goes beyond simple text extraction. Multi-column layouts are analyzed to determine the correct reading order across columns, so that content that spans multiple columns in the original document is reconstructed in the sequence that preserves its meaning. Headers and footers are identified and removed from the main content stream, ensuring that repetitive navigational text does not pollute the extracted content. Page numbers are excluded from the content output.

Table extraction converts tables to HTML that preserves the full row-column structure, including merged cells and header rows. Cross-page tables, where a table spans a page boundary, are detected and merged into a single output table rather than being split at the page boundary. The 3.1.0 release added image recognition inside tables, handling the increasingly common case where charts or images are embedded within table cells.

Formula extraction converts both inline and display mathematical notation to LaTeX format. The formula recognition system handles the full range of mathematical notation including Greek letters, mathematical operators, fractions, integrals, summations, matrices, and complex multi-level expressions. Formulas are extractable as independent units and are also preserved in their correct position within the surrounding text flow.

Truncated paragraph merging handles the case where paragraphs that span page boundaries in the original document need to be reconstructed as coherent units in the extracted output. This is particularly important for long-form documents where paragraph continuity across pages is necessary for coherent chunking.

Architecture for High-Throughput Production Deployment

Enterprise document processing at scale requires architecture that goes beyond single-machine parsing. MinerU 3.0 introduced a router and API framework designed specifically for high-concurrency, high-throughput production deployment.

The mineru-api service provides both asynchronous and synchronous endpoints. The asynchronous endpoint accepts task submissions and returns a task identifier that clients can use to query status and retrieve results when processing completes. This is the appropriate interface for batch processing workflows where individual documents may take significant time to parse. The synchronous endpoint is retained for compatibility with existing integration patterns and for use cases where immediate results are required.

The mineru-router component provides unified entry deployment and task routing across multiple service instances and multiple GPUs. Its interface is fully compatible with mineru-api, allowing it to be substituted transparently as a load-balancing layer in front of multiple parsing instances. Automatic task load balancing distributes work across available instances without requiring application-level routing logic.

Thread-safety optimization in 3.0 enables fully concurrent multi-threaded inference on a single machine, improving resource utilization and throughput on hardware with multiple CPU cores or multiple GPUs. Combined with mineru-router, this creates a straightforward path to building parsing infrastructure that can handle large document volumes with consistent throughput.

The sliding window mechanism for long documents addresses the peak memory problem that previously made documents with tens of thousands of pages impractical to process without manual splitting. The sliding window approach maintains bounded peak memory usage regardless of document length, allowing arbitrarily long documents to be processed in a single pipeline invocation. Streaming writes to disk for batch inference allow completed parsing results to be written as they finish rather than accumulating in memory until the entire batch is complete, further reducing memory pressure for large batch workloads.

The Role of MinerU in GraphRAG and Agentic Workflows

The quality of structured extraction from MinerU makes it particularly valuable for knowledge graph construction and GraphRAG architectures, which depend on being able to identify entities, relationships, and structured data within document content.

Standard flat-text extraction loses the structural cues that identify tables as relational data, formulas as mathematical relationships, and hierarchical headings as organizational structure. MinerU’s preservation of these structures in its output provides the downstream knowledge extraction pipeline with the signals it needs to construct accurate knowledge graphs. A table extracted as HTML with row and column relationships intact can be processed by a knowledge graph pipeline to extract structured facts. A formula extracted as LaTeX can be processed to identify mathematical relationships. A document outline preserved through heading extraction can be used to construct a hierarchical knowledge structure.

For agentic workflows that involve reading and analyzing large volumes of technical documentation, legal documents, financial reports, or research literature, the quality of document parsing directly affects the quality of the agent’s reasoning. An agent that receives coherent, structurally faithful document representations can extract relevant information, identify contradictions, follow cross-references, and reason about the relationships between content elements. An agent working with degraded parsing output must work around incoherent content, missing context, and lost structural relationships.

The JSON output format from MinerU, sorted by reading order and preserving the hierarchical structure of the document, is designed for programmatic consumption by agentic systems and data pipelines. The rich intermediate formats support inspection and quality verification before feeding parsed content into downstream systems.

Output Formats and Quality Verification

MinerU produces multiple output formats to accommodate different downstream use cases. The multimodal Markdown format preserves text content alongside references to extracted images and formatted tables, producing a representation suitable for human review and for direct use in RAG chunking workflows. The NLP-focused Markdown format is optimized for text-only processing pipelines where image references are not needed. The JSON output sorted by reading order provides a structured representation suitable for programmatic processing by downstream systems. Rich intermediate formats expose the detailed output of the layout analysis and span detection stages for inspection and debugging.

Visualization outputs showing layout bounding boxes and span detection results allow quality verification before committing parsed content to production pipelines. For documents with unusual layouts or challenging content, these visualizations make it straightforward to identify parsing issues and assess whether additional preprocessing or configuration adjustments are needed.

The built-in Gradio WebUI provides an interface for interactive testing and quality evaluation without requiring command-line usage. The FastAPI service enables integration with existing web-based workflows and microservice architectures. The CLI provides the direct command-line interface for scripted and batch processing workflows.

Conclusion

MinerU addresses one of the most consequential but least discussed problems in enterprise AI deployment: the gap between the theoretical capability of retrieval and generation systems and the practical quality of the document parsing that feeds them. No retrieval architecture, chunking strategy, or embedding model can compensate for structure lost at the parsing stage. Building reliable knowledge systems on poorly parsed documents is building on an unreliable foundation.

The combination of high-accuracy structure preservation across complex document types, multilingual OCR covering 109 languages, support for all major enterprise document formats including PDF, DOCX, PPTX, and XLSX, multiple deployment backends covering CPU-only through high-throughput multi-GPU configurations, and a production-ready router and API framework makes MinerU a comprehensive solution for the document preparation layer of enterprise AI systems.

For teams building RAG systems, GraphRAG pipelines, document-aware agents, or internal knowledge bases, MinerU provides the parsing foundation that makes the entire downstream architecture more reliable. The most effective investment in RAG quality is often not in the retrieval or generation components but in ensuring that the documents entering the system retain their structure through the parsing step.

The repository is available at: https://github.com/opendatalab/mineru