DOCSEARCHbyAlgolia
Submit Docs

MinerU Document Parsing Tool

repository·master·Indexed 13 days ago

https://github.com/opendatalab/mineru

A high-performance document parsing tool that converts PDF, images, DOCX, PPTX, and XLSX into structured Markdown and JSON. It features layout cleaning, structure preservation, formula conversion to LaTeX, and OCR support for 109 languages. MinerU provides an orchestration-based architecture including a CLI, mineru-api, mineru-router for multi-GPU load balancing, and a Gradio WebUI. It supports deployment across Windows, Linux, and macOS using CPU, GPU (CUDA), NPU (CANN), or MPS acceleration.

Tokens
31.3K
Snippets
99
Records
152
Agent score
98%

What's inside MinerU

  1. What is MinerU?

    master

    MinerU is a document parsing tool designed to convert various file formats into machine-readable formats like Markdown and JSON. It is optimized for downstream tasks such as retrieval, extraction, and processing in large model workflows.

    Supported Input Formats:

    • PDF
    • Images
    • DOCX
    • PPTX
    • XLSX

    Key Capabilities:

    • Layout Cleaning: Removes headers, footers, footnotes, and page numbers to maintain semantic coherence.
    • Structure Preservation: Retains titles, paragraphs, and lists in human reading order (supporting single-column, multi-column, and complex layouts).
    • Element Extraction: Extracts images (with descriptions), tables (converted to HTML), and footnotes.
    • Formula Conversion: Automatically identifies and converts mathematical formulas into LaTeX format.
    • OCR Support: Detects scanned or garbled PDFs and enables OCR for 109 languages.
    • Deployment Options: Includes a built-in CLI, FastAPI, and Gradio WebUI. It supports CPU, GPU (CUDA), NPU (CANN), and MPS acceleration across Windows, Linux, and Mac.

  2. Overview of MinerU Document Parsing Engine

    master

    MinerU is a high-precision document parsing engine designed for LLM, RAG, and Agent scenarios. It converts various file formats into structured Markdown or JSON.

    Core Capabilities:

    • Supported Formats: PDF, DOCX, PPTX, XLSX, Images, and Webpages.
    • High-Fidelity Extraction: Converts formulas to LaTeX and tables to HTML, accurately restoring complex layouts.
    • Advanced Layout Handling: Supports scanned documents, handwriting, multi-column layouts, and merging tables across pages.
    • Clean Output: Produces output following human reading order and automatically removes headers and footers.
    • Dual Engine: Uses VLM + OCR dual engines supporting recognition for 109 languages.

    Deployment Options:

    • pipeline: Fast and stable; runs on both CPU and GPU without hallucinations.
    • vlm-engine: High precision; supports vLLM, LMdeploy, and mlx ecosystems.
    • hybrid-engine: High precision with native text extraction and low hallucination.

  3. Overview of MinerU capabilities

    master

    MinerU is a document parsing tool designed to convert PDF, images, DOCX, PPTX, and XLSX files into machine-readable formats like Markdown and JSON. It is optimized for scientific literature and complex layouts.

    Key Features:

    • Format Support: Native parsing for PDF, images, DOCX, PPTX, and XLSX.
    • Layout Cleaning: Automatically removes headers, footers, footnotes, and page numbers to ensure semantic continuity.
    • Structure Preservation: Maintains titles, paragraphs, and lists in human-readable order (supporting single and multi-column layouts).
    • Element Extraction: Extracts images, image descriptions, tables, table captions, and footnotes.
    • Formula & Table Conversion: Automatically converts formulas to LaTeX and tables to HTML.
    • OCR Capabilities: Automatically detects scanned or garbled PDFs and enables OCR (supporting 109 languages).
    • Output Formats: Supports Markdown (for NLP/Multimodal), JSON (ordered by reading sequence), and intermediate formats.
    • Deployment Options: Includes CLI, FastAPI, and Gradio WebUI. Supports CPU-only environments, GPU/MPS acceleration, and various domestic computing platforms across Windows, Linux, and macOS.

  4. Overview of MinerU features and supported formats

    master

    MinerU is a document parsing tool that converts various document formats into machine-readable formats like Markdown and JSON. It is designed for downstream retrieval, extraction, and processing tasks.

    Supported Input Formats:

    • PDF (including scanned and garbled PDFs via OCR)
    • Images
    • DOCX (native parsing supported)
    • PPTX (native parsing supported)
    • XLSX (native parsing supported)

    Key Capabilities:

    • Layout Cleaning: Removes headers, footers, footnotes, and page numbers to maintain semantic coherence.
    • Structure Preservation: Maintains headings, paragraphs, and lists in human-readable order (supporting single/multi-column layouts).
    • Element Extraction: Extracts images, descriptions, tables, titles, and footnotes.
    • Conversion: Automatically converts formulas to LaTeX and tables to HTML.
    • OCR: Supports 109 languages and automatically detects when OCR is needed for scanned documents.
    • Output Formats: Supports multimodal Markdown, NLP Markdown, and JSON sorted by reading order.
    • Deployment: Supports CLI, FastAPI, Gradio WebUI, and multi-GPU deployment via mineru-router. Works on Windows, Linux, and macOS in CPU, GPU, or MPS environments.

  5. Understand MinerU output file types

    master

    When running the mineru command, the tool generates several auxiliary files alongside the main markdown output. These files are categorized into:

    • Visual debugging files: Used for intuitive inspection of the parsing process (e.g., layout and text spans).
    • Structured data files: Contain detailed parsing data intended for secondary development or programmatic processing.
    • Multimodal markdown content: In outputs containing images or charts, the markdown includes a screenshot followed by a collapsed HTML <details> block containing the raw content if available. The summary label for the <details> block uses the block's sub_type, falling back to image content or chart content if sub_type is missing.

  6. Hardware and Software Requirements for MinerU

    master

    MinerU supports multiple parsing backends with varying hardware requirements. Choose the backend based on your available resources:

    Backend Comparison

    Featurepipeline (hybrid)pipeline (vlm)*-engine (hybrid)*-engine (vlm)*-http-client (hybrid)*-http-client (vlm)
    Best ForGood CompatibilityHigh AccuracyHigh AccuracyHigh AccuracyOpenAI Compatible ServersOpenAI Compatible Servers
    Pure CPU Support✅❌❌❌✅
    Min VRAM4GB8GB8GB8GB2GB
    Min RAM16GB+ (Rec 32GB+)16GB+ (Rec 32GB+)16GB+ (Rec 32GB+)16GB+ (Rec 32GB+)16GB
    Disk Space20GB+ (SSD Rec)20GB+ (SSD Rec)20GB+ (SSD Rec)20GB+ (SSD Rec)2GB

    System Support

    • Python Version: 3.10 - 3.13
    • Operating Systems:
      • Linux: Distributions from 2019 and later.
      • Windows: Python 3.10 - 3.12 (due to ray dependency limitations on 3.13).
      • macOS: Version 14.0 or later.
    • GPU Acceleration: Volta and later architecture GPUs or Apple Silicon.

  7. Deploy MinerU with API, CLI, and Router

    master

    MinerU has evolved from a single tool into an orchestratable system for high-concurrency, high-throughput document parsing. The architecture includes:

    • mineru (Orchestration Client): Acts as the client. If no --api-url is provided, it automatically starts a local temporary service.
    • mineru-api: The backend service. It provides:
      • POST /tasks: An asynchronous interface for task submission, status querying, and result retrieval.
      • POST /file_parse: A synchronous interface maintained for compatibility with older plugins.
    • mineru-router: A unified entry point for multi-service or multi-GPU deployments. It is fully compatible with the mineru-api interface and supports automatic task load balancing across multiple workers.

  8. Use the MinerU orchestration framework (API, CLI, and Router)

    master

    MinerU has evolved from a standalone tool into an orchestration-based system:

    • CLI Orchestration: The mineru CLI acts as an orchestration client. If the --api-url flag is not provided, it automatically starts a local temporary service.
    • mineru-api: Provides two types of endpoints:
      • POST /tasks: An asynchronous endpoint for task submission, status querying, and result retrieval.
      • POST /file_parse: A synchronous endpoint maintained for compatibility with legacy plugins.
    • mineru-router: A component designed for unified entry deployment. It routes tasks across multiple services and multiple GPUs, supporting automatic task load balancing. It is fully compatible with mineru-api interfaces.

  9. Switch MinerU model sources

    master

    MinerU supports three model source policies: huggingface, modelscope, and local.

    • auto (Default): MinerU first attempts to access Hugging Face. If successful, it uses huggingface; otherwise, it falls back to modelscope. Once an auto-probe resolves, MinerU updates your configuration to the specific source to prevent future network-related switching.
    • huggingface: Best for global stability and loading speed.
    • modelscope: Recommended for users in mainland China who cannot access Hugging Face.
    • local: Uses models already downloaded to your local storage.

    Note: MinerU does not provide a CLI flag for model source selection. You must use environment variables or the configuration file.

  10. Configure parsing strength with the effort parameter

    master

    The Hybrid backend supports an effort parameter to balance parsing speed and accuracy.

    • effort=medium: The default setting. It provides significant speed improvements (e.g., ~80% faster for text PDFs on Linux) while maintaining high accuracy. Note: medium does not support image analysis.
    • effort=high: Designed for maximum parsing accuracy or when image analysis is required. This may impact parsing speed.

  11. Getting Started with MinerU 3.0

    master

    Starting with version 3.0, mineru operates as an orchestration client that runs on top of mineru-api. For complex deployments involving multi-service or multi-GPU setups, you can utilize mineru-router.

    To master the project, it is recommended to follow the documentation in this order:

    1. Quick Usage: For initial setup and basic operations.
    2. Model Source Configuration: To configure where models are sourced from.
    3. Command Line Tools: To understand the available CLI commands and their parameters.
    4. Advanced Optimization Parameters: To fine-tune CLI tool performance and behavior.

  12. Deploy MinerU using Docker

    master

    Docker deployment is available to help manage environment compatibility issues.

    Important Constraints:

    • Supported OS: Only Linux and Windows (with WSL2 support).
    • macOS Users: Do NOT use Docker; use the pip/uv or source installation methods instead.

    Refer to the docker_deployment.md file in the repository for detailed instructions.