MinerU User Guide

MinerU is a high-accuracy document parsing tool from OpenDataLab that converts PDFs, images, and Office files (DOCX, PPTX, XLSX) into structured Markdown and JSON. It combines deep learning models for layout detection, OCR, formula recognition, and table extraction into a unified pipeline that handles everything from clean digital PDFs to messy scanned documents.

MinerU ships with a CLI (mineru), a FastAPI server (mineru-api), a Gradio web UI (mineru-gradio), a multi-GPU load-balancing router (mineru-router), and an OpenAI-compatible VLM inference server (mineru-openai-server). Five parsing backends cover the spectrum from traditional OCR pipelines to vision-language-model approaches, with a hybrid mode that combines both for best results.

1. Quick Start

1.1 Minimal Setup

# Install MinerU (requires Python 3.9+, CUDA-capable GPU recommended)
pip install mineru

# Download the required models
download-models

# Parse a PDF to Markdown
mineru -p document.pdf -o ./output

The output directory will contain:

output/
  document/
    document.md           # Structured Markdown
    content_list.json     # Parsed content blocks
    model_output.json     # Raw model predictions
    images/               # Extracted images

Note

The first run downloads several GB of deep learning models (layout detection, OCR, formula, table). Subsequent runs reuse the cached models. Set MINERU_MODEL_SOURCE=modelscope if Hugging Face is slow in your region.

1.2 Quick Web UI

For users who prefer a graphical interface:

mineru-gradio

Open http://localhost:7860 in your browser, upload a file, and click Convert. The Gradio UI supports all the same backends and options as the CLI.

1.3 Five-Minute API Server

# Start the API server
mineru-api --host 0.0.0.0 --port 8000

# Submit a file for parsing (from another terminal)
curl -X POST http://localhost:8000/file_parse \
  -F "file=@document.pdf" \
  -F "parse_method=auto" \
  -o result.zip

2. Installation

2.1 pip Install (Recommended)

pip install mineru

This installs the mineru, mineru-api, mineru-gradio, mineru-router, mineru-openai-server, and download-models commands.

Important

MinerU requires a CUDA-capable NVIDIA GPU for full performance. CPU-only mode works but is significantly slower. Ensure your CUDA toolkit and PyTorch CUDA versions are compatible.

2.2 Download Models

After installing the package, download the required deep learning models:

# Default: download from Hugging Face
download-models

# Use ModelScope (faster in China)
download-models -s modelscope

# Download only a specific model type
download-models -m layout

Models are stored in the directory specified by the models-dir field in your mineru.json config file. If no config exists, models go to the default cache location.

2.3 Docker Installation

MinerU provides a Docker Compose setup with four service profiles. An NVIDIA GPU with the NVIDIA Container Toolkit is required.

# Clone the repository
git clone https://github.com/opendatalab/MinerU.git
cd MinerU

# Start the API server
docker compose --profile api up -d

# Or start the Gradio web UI
docker compose --profile gradio up -d

# Or start the multi-GPU router
docker compose --profile router up -d

# Or start the OpenAI-compatible VLM server
docker compose --profile openai-server up -d

2.4 Verifying the Installation

# Check that the CLI is available
mineru --help

# Parse a small test file
mineru -p test.pdf -o ./test_output

# Check API server health
curl http://localhost:8000/health

Tip

If you get import errors related to PyTorch or CUDA, verify your CUDA version with nvidia-smi and ensure your PyTorch installation matches. MinerU relies on GPU-accelerated inference for layout detection, OCR, and formula recognition.

3. Configuration

3.1 Config File: mineru.json

MinerU reads its configuration from mineru.json. A template is provided at mineru.template.json in the repository. The config file name can be overridden via the MINERU_TOOLS_CONFIG_JSON environment variable.

{
    "bucket_info": {
        "bucket-name-1": ["ak", "sk", "endpoint"]
    },
    "latex-delimiter-config": {
        "display": {"left": "$$", "right": "$$"},
        "inline": {"left": "$", "right": "$"}
    },
    "llm-aided-config": {
        "title_aided": {
            "api_key": "your_api_key",
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "model": "qwen3.5-plus",
            "enable_thinking": false,
            "enable": false
        }
    },
    "models-dir": {
        "pipeline": "",
        "vlm": ""
    },
    "config_version": "1.3.1"
}

Key sections:

3.2 Essential Environment Variables

These environment variables control runtime behavior without editing config files:

Tip

For a complete list of all environment variables and advanced configuration options (virtual VRAM, API concurrency limits, router GPU assignments), see the Admin Guide.

3.3 LaTeX Delimiter Configuration

Control how mathematical expressions appear in the Markdown output:

{
    "latex-delimiter-config": {
        "display": {"left": "$$", "right": "$$"},
        "inline": {"left": "$", "right": "$"}
    }
}

The Gradio UI also accepts a --latex-delimiters-type flag (default all) to control delimiter rendering in the preview.

3.4 LLM-Aided Title Detection

MinerU can optionally use an external LLM to improve heading/title recognition. This requires an API key for a compatible service:

{
    "llm-aided-config": {
        "title_aided": {
            "api_key": "your_api_key",
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "model": "qwen3.5-plus",
            "enable_thinking": false,
            "enable": true
        }
    }
}

Set "enable": true to activate. This is optional and MinerU works well without it.

4. Core Usage

4.1 CLI Parsing: The mineru Command

The primary interface for document parsing:

mineru -p <input> -o <output_dir> [options]

Required arguments:

Common options:

Examples:

# Parse a PDF with default settings (hybrid backend, auto method)
mineru -p report.pdf -o ./output

# Parse only pages 5-10
mineru -p report.pdf -o ./output -s 5 -e 10

# Force OCR mode for a scanned PDF
mineru -p scanned.pdf -o ./output -m ocr

# Use the VLM backend
mineru -p report.pdf -o ./output -b vlm-auto-engine

# Parse a directory of files
mineru -p ./documents/ -o ./output

# Disable formula recognition for faster processing
mineru -p report.pdf -o ./output -f false

# Parse a Word document
mineru -p presentation.pptx -o ./output

4.2 Choosing a Backend

MinerU provides five backends that balance accuracy, speed, and resource requirements:

# Default hybrid backend
mineru -p doc.pdf -o out -b hybrid-auto-engine

# Traditional pipeline (lower VRAM, still good quality)
mineru -p doc.pdf -o out -b pipeline

# VLM only (requires VLM models downloaded)
mineru -p doc.pdf -o out -b vlm-auto-engine

# Remote VLM server
mineru -p doc.pdf -o out -b vlm-http-client -u http://gpu-server:30000

Note

The hybrid-auto-engine backend is the default because it combines the strengths of both approaches. If VRAM is limited, fall back to pipeline. If you have a dedicated GPU server, hybrid-http-client or vlm-http-client offloads the heavy VLM inference.

4.3 Parse Methods

The parse method controls how text is extracted from PDFs. This setting applies only to the pipeline and hybrid backends.

# Let MinerU decide per page
mineru -p mixed.pdf -o out -m auto

# Force text extraction (fast, for clean digital PDFs)
mineru -p digital.pdf -o out -m txt

# Force OCR (for scanned documents)
mineru -p scan.pdf -o out -m ocr

When to use each method:

• auto — Works for most documents. MinerU detects whether each page has extractable text or is image-based.
• txt — Use when you know the PDF is digitally generated (not scanned). Faster and more accurate for clean text.
• ocr — Use for scanned documents, photographed pages, or PDFs where embedded text is garbled/missing.

4.4 OCR Language Support

Set the OCR language hint to improve recognition accuracy for non-English documents:

# Chinese (default)
mineru -p chinese_doc.pdf -o out -l ch

# English
mineru -p english_doc.pdf -o out -l en

# Japanese
mineru -p japanese_doc.pdf -o out -l ja

The -l flag provides a language hint to the OCR engine (PytorchPaddle). The default is ch (Chinese), which also handles English well. For best results with other languages, specify the appropriate language code.

4.5 Understanding the Output

After parsing, MinerU produces several output files:

output/
  document_name/
    document_name.md           # Primary Markdown output
    content_list.json          # Structured content blocks with positions
    model_output.json          # Raw model detection results
    images/                    # Extracted images referenced by the Markdown
      img_0_0.png
      img_0_1.png
      ...

4.6 Using the API Server

Starting the Server

# Local-only access
mineru-api

# Allow external connections
mineru-api --host 0.0.0.0 --port 8000

# Enable auto-reload during development
mineru-api --reload

# Allow public HTTP client backends
mineru-api --allow-public-http-client

# Preload VLM models for faster first request
mineru-api --enable-vlm-preload

API Endpoints

Synchronous Parsing

curl -X POST http://localhost:8000/file_parse \
  -F "file=@document.pdf" \
  -F "parse_method=auto" \
  -o result.zip

The response is a ZIP file containing the Markdown, JSON, and images.

Asynchronous Parsing

For large documents, use the async workflow to avoid timeouts:

# Submit a task
TASK_ID=$(curl -s -X POST http://localhost:8000/tasks \
  -F "file=@large_document.pdf" \
  -F "parse_method=auto" | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# Poll for completion
curl -s http://localhost:8000/tasks/$TASK_ID/status

# Download the result when status is "completed"
curl http://localhost:8000/tasks/$TASK_ID/result -o result.zip

Warning

The synchronous /file_parse endpoint blocks the connection until parsing finishes. For documents longer than ~50 pages, use the async /tasks endpoint to avoid HTTP timeouts.

4.7 Using the Gradio Web UI

# Start with defaults
mineru-gradio

# Custom port and server name
mineru-gradio --server-name 0.0.0.0 --server-port 7860

# Connect to an existing API server
mineru-gradio --api-url http://localhost:8000

# Enable HTTP client backends in the UI
mineru-gradio --enable-http-client

# Limit max pages per conversion
mineru-gradio --max-convert-pages 100

# Preload VLM models
mineru-gradio --enable-vlm-preload

4.8 Multi-GPU Load Balancing with the Router

For high-throughput scenarios, mineru-router distributes parsing work across multiple GPUs or upstream servers:

# Auto-detect local GPUs
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

# Specify GPUs explicitly
mineru-router --local-gpus 0,1,2,3

# Add remote upstream servers
mineru-router --upstream-url http://server1:8000 --upstream-url http://server2:8000

# Disable local GPUs, route to remote servers only
mineru-router --local-gpus none --upstream-url http://server1:8000

# Preload VLM models on all workers
mineru-router --enable-vlm-preload

The router exposes the same API endpoints as mineru-api, so clients can use it as a drop-in replacement.

Tip

Use the router environment variables MINERU_ROUTER_LOCAL_GPUS and MINERU_ROUTER_WORKER_HOST to configure routing via environment instead of CLI flags. This is useful in Docker and orchestration environments.

4.9 VLM Inference Server

The mineru-openai-server provides an OpenAI-compatible API for VLM inference. This is used by the vlm-http-client and hybrid-http-client backends:

# Start with auto-detected inference engine
mineru-openai-server

# Specify the inference engine
mineru-openai-server -e vllm

The server runs on port 30000 by default and accepts standard OpenAI-format requests. Point the vlm-http-client or hybrid-http-client backend at this server with the -u flag:

# On the GPU server
mineru-openai-server

# On the client machine
mineru -p doc.pdf -o out -b vlm-http-client -u http://gpu-server:30000

5. Common Tasks

5.1 Convert a Single PDF to Markdown

mineru -p report.pdf -o ./output

Output: ./output/report/report.md plus supporting JSON and images.

5.2 Batch Convert a Directory of Files

mineru -p ./documents/ -o ./output

MinerU processes all supported files in the directory. Each file gets its own subdirectory in the output.

5.3 Parse Only Specific Pages

# Pages 0 through 4 (first 5 pages, 0-based indexing)
mineru -p report.pdf -o ./output -s 0 -e 4

# Just page 10
mineru -p report.pdf -o ./output -s 10 -e 10

Note

Page numbers are 0-based. Page 0 is the first page of the document.

5.4 Handle Scanned Documents

For image-based or scanned PDFs, force OCR mode:

mineru -p scanned_contract.pdf -o ./output -m ocr -l en

Set the -l language flag to match the document language for best accuracy.

5.5 Extract Tables from a PDF

Tables are extracted by default. MinerU uses SLANet+ for wireless (borderless) tables and UNet for wired (bordered) tables, with PaddleTableCls selecting the right model automatically.

# Standard extraction (tables enabled by default)
mineru -p financial_report.pdf -o ./output

# Disable table extraction if not needed (faster)
mineru -p report.pdf -o ./output -t false

Tables appear as Markdown tables in the .md output and as structured blocks in content_list.json.

5.6 Extract Mathematical Formulas

Formula recognition uses Unimernet (or PP FormulaNet Plus M for Chinese formulas). Enabled by default.

# Parse a paper with formulas
mineru -p research_paper.pdf -o ./output

# Customize LaTeX delimiters in mineru.json
# Display math: $$ ... $$
# Inline math: $ ... $

Formulas appear as LaTeX in the Markdown output, wrapped in the delimiters configured in mineru.json.

5.7 Parse Office Documents

MinerU handles DOCX, PPTX, and XLSX files:

# Word document
mineru -p proposal.docx -o ./output

# PowerPoint presentation
mineru -p slides.pptx -o ./output

# Excel spreadsheet
mineru -p data.xlsx -o ./output

5.8 Parse Images Directly

Feed individual images (PNG, JPG, JPEG, TIFF, WebP, GIF, BMP, JP2) for OCR:

mineru -p photograph.jpg -o ./output
mineru -p whiteboard.png -o ./output -l en

5.9 Use a Remote VLM Server for Higher Quality

Split the workload: run the VLM inference on a powerful GPU server, and the rest locally:

# On the GPU server (e.g., A100)
mineru-openai-server

# On your local machine
mineru -p document.pdf -o ./output -b hybrid-http-client -u http://gpu-server:30000

This gives you hybrid-quality results without needing a large local GPU.

5.10 Set Up a Production API Service

# Start the API server on all interfaces
mineru-api --host 0.0.0.0 --port 8000

# For multi-GPU setups, use the router instead
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

Control API concurrency with the environment variable:

export MINERU_API_MAX_CONCURRENT_REQUESTS=4
mineru-api --host 0.0.0.0

5.11 Run the Gradio UI with an Existing API Backend

If you already have mineru-api running, point Gradio at it instead of spinning up another backend:

mineru-gradio --api-url http://localhost:8000

5.12 Select a Specific GPU

# Use only GPU 1
CUDA_VISIBLE_DEVICES=1 mineru -p doc.pdf -o out

# Use GPUs 0 and 2
CUDA_VISIBLE_DEVICES=0,2 mineru-router --local-gpus auto

5.13 Speed Up Processing by Disabling Unused Features

# Disable both formula and table recognition
mineru -p text_only.pdf -o out -f false -t false

Or set environment variables for session-wide defaults:

export MINERU_FORMULA_ENABLE=false
export MINERU_TABLE_ENABLE=false
mineru -p doc.pdf -o out

5.14 Change the Model Download Source

# Download from ModelScope instead of Hugging Face
export MINERU_MODEL_SOURCE=modelscope
download-models

# Or pass it directly
download-models -s modelscope

5.15 Enable Debug Logging

MINERU_LOG_LEVEL=DEBUG mineru -p doc.pdf -o out

This produces verbose output showing each model's detection results, timing information, and processing decisions.

6. Troubleshooting

6.1 Installation & Model Issues

Error: Models not found or download fails

Cause: Model weights have not been downloaded, or the download was interrupted.

Solution:

# Re-run the model downloader
download-models

# If Hugging Face is unreachable, switch to ModelScope
download-models -s modelscope

# Verify models-dir in mineru.json points to the right location

Prevention: Always run download-models after installation or upgrade. Check that the models-dir paths in mineru.json are correct if you customized them.

Error: CUDA out of memory

Cause: The GPU does not have enough VRAM for the selected backend and document.

Solution:

• Switch from hybrid-auto-engine to pipeline (lower VRAM):

  mineru -p doc.pdf -o out -b pipeline
  

• Disable formula or table recognition:

  mineru -p doc.pdf -o out -f false -t false
  

• Restrict to a GPU with more VRAM:

  CUDA_VISIBLE_DEVICES=0 mineru -p doc.pdf -o out
  

• Set virtual VRAM size via MINERU_VIRTUAL_VRAM_SIZE (see Admin Guide)

Prevention: The hybrid-auto-engine backend loads both pipeline and VLM models. For GPUs with less than 16 GB VRAM, prefer the pipeline backend.

Error: PyTorch / CUDA version mismatch

Cause: The installed PyTorch was compiled for a different CUDA version than what is available on the system.

Solution:

# Check your CUDA version
nvidia-smi

# Reinstall PyTorch for your CUDA version
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

6.2 Parsing Issues

Error: Timed out while polling task status

Cause: The async task took longer than the client's polling timeout. Related to GitHub issue #4792.

Solution:

• Increase the polling timeout in your client code
• For very large documents, parse a page range instead:

  mineru -p large.pdf -o out -s 0 -e 49
  

• Increase MINERU_PDF_RENDER_TIMEOUT if the rendering step is the bottleneck

Error: Image segmentation anomaly

Cause: Layout detection model produces unexpected segmentation results. Related to GitHub issue #4008.

Solution:

• Try a different backend:

  mineru -p doc.pdf -o out -b vlm-auto-engine
  

• If specific pages are affected, parse the rest separately and merge outputs

Error: Table extraction produces incorrect results

Cause: Complex table layouts (merged cells, nested tables, borderless tables) can challenge the table recognition models. Related to GitHub issue #4207.

Solution:

• Try the VLM backend, which often handles complex tables better:

  mineru -p doc.pdf -o out -b vlm-auto-engine
  

• Check content_list.json for the raw table data, which may have better structure than the Markdown rendering
• For borderless tables, ensure MINERU_TABLE_MERGE_ENABLE=true (the default)

Error: LaTeX symbols not rendering correctly in Markdown

Cause: LaTeX delimiter configuration mismatch between MinerU output and the Markdown renderer. Related to GitHub issue #1717.

Solution: Adjust the delimiter configuration in mineru.json:

{
    "latex-delimiter-config": {
        "display": {"left": "$$", "right": "$$"},
        "inline": {"left": "$", "right": "$"}
    }
}

Ensure your Markdown viewer supports the chosen delimiters. Some viewers expect \( and \) for inline math.

6.3 Arabic and RTL Language Issues

Error: Arabic PDF text appears in wrong order

Cause: Right-to-left text extraction can produce reversed or misordered output. Related to GitHub issue #2551.

Solution:

• Use OCR mode instead of text extraction:

  mineru -p arabic.pdf -o out -m ocr -l ar
  

• The VLM backend may handle RTL layout better than the pipeline

Error: Arabic language recognition failures

Cause: OCR language model not configured for Arabic. Related to GitHub issue #1367.

Solution:

mineru -p arabic.pdf -o out -m ocr -l ar

Ensure the Arabic OCR model is downloaded. If recognition is still poor, try the VLM backend.

6.4 Server & API Issues

Error: 910B vllm-ascend service timeout

Cause: VLM inference on Ascend 910B hardware timing out. Related to GitHub issue #4796.

Solution:

• Check that the Ascend NPU drivers and vllm-ascend are correctly installed
• Increase timeout settings
• Verify the device is accessible via MINERU_LMDEPLOY_DEVICE

Error: Atlas 300I tasks stuck in processing

Cause: Tasks submitted to Atlas 300I hardware not completing. Related to GitHub issue #4795.

Solution:

• Check device availability and driver status
• Restart the API server
• Check logs with MINERU_LOG_LEVEL=DEBUG

Error: Path issues after upgrading MinerU >3.0 with RagFlow

Cause: Breaking path changes in MinerU 3.x. Related to GitHub issue #4696.

Solution:

• Update the integration paths in RagFlow to match the new MinerU 3.x API
• Check the MinerU migration documentation for path changes between versions

Caution

MinerU 3.x introduced breaking changes to its Python API and file output paths. If you are upgrading from 2.x, review the changelog and update any scripts or integrations that reference internal paths or APIs.

Error: API server not responding to health checks

Cause: Server failed to start, port conflict, or models not loaded.

Solution:

# Check if the port is in use
lsof -i :8000

# Start with debug logging
MINERU_LOG_LEVEL=DEBUG mineru-api --host 0.0.0.0 --port 8000

# Verify health endpoint
curl http://localhost:8000/health

6.5 Performance Issues

Parsing is very slow

Cause: Running on CPU, too many features enabled, or oversized documents.

Solution:

• Confirm GPU is being used (check nvidia-smi during parsing)
• Disable unused features:

  mineru -p doc.pdf -o out -f false -t false
  

• Parse page ranges for large documents
• Use the router with multiple GPUs for throughput
• Increase MINERU_PDF_RENDER_THREADS for faster page rendering
• Adjust MINERU_PROCESSING_WINDOW_SIZE for batch tuning

7. FAQ

Q: What file formats does MinerU support as input?

PDF, PNG, JPG, JPEG, JP2, WebP, GIF, BMP, TIFF (images), DOCX, PPTX, and XLSX. All are processed through the same pipeline and produce Markdown + JSON output.

Q: Which backend should I use?

Start with the default hybrid-auto-engine. If you have limited GPU memory, use pipeline. If you have a dedicated GPU server, use hybrid-http-client to offload VLM inference. Use vlm-auto-engine or vlm-http-client if you want pure VLM-based parsing.

Q: Does MinerU require a GPU?

A CUDA-capable NVIDIA GPU is strongly recommended. MinerU can run on CPU but will be significantly slower since it uses deep learning models for layout detection, OCR, formula recognition, and table extraction.

Q: How much VRAM do I need?

The pipeline backend works with 8+ GB VRAM. The hybrid-auto-engine backend (default) loads both pipeline and VLM models, so 16+ GB is recommended. Reduce VRAM usage by disabling formula (-f false) or table (-t false) recognition.

Q: What is the difference between auto, txt, and ocr parse methods?

auto lets MinerU decide per page whether to extract embedded text or run OCR. txt forces text extraction (fast, for digital PDFs). ocr forces optical character recognition (for scanned/image PDFs). The method flag only applies to pipeline and hybrid backends.

Q: Can I process password-protected PDFs?

MinerU does not handle encrypted/password-protected PDFs. Remove the password protection first using a tool like qpdf:

qpdf --decrypt --password=mypassword protected.pdf unlocked.pdf
mineru -p unlocked.pdf -o out

Q: How do I use MinerU with Chinese documents?

Chinese is the default OCR language (-l ch). For Chinese mathematical formulas, MinerU automatically uses PP FormulaNet Plus M. No special configuration is needed.

Q: Can I run multiple MinerU instances on different GPUs?

Yes. Use CUDA_VISIBLE_DEVICES to assign each instance to a different GPU, or use mineru-router which handles multi-GPU distribution automatically:

mineru-router --local-gpus 0,1,2,3 --host 0.0.0.0

Q: How do I customize the Markdown output format?

The primary customization is LaTeX delimiters via mineru.json. The structure of the Markdown output (headings, tables, images) is determined by the layout detection model and is not configurable per-run.

Q: Where are the downloaded models stored?

By default, models are cached in the standard Hugging Face or ModelScope cache directory. Override this by setting the models-dir field in mineru.json:

{
    "models-dir": {
        "pipeline": "/path/to/pipeline/models",
        "vlm": "/path/to/vlm/models"
    }
}

Q: Can MinerU be used as a Python library (not just CLI)?

Yes. MinerU's Python packages can be imported directly. However, the public Python API changed significantly in version 3.x. Refer to the repository's Python API documentation for current import paths and usage patterns.

Important

If you are integrating MinerU as a library in another application (such as RagFlow), pin the MinerU version in your requirements and test thoroughly after upgrades. The 3.x release introduced breaking API changes (see issue #4696).

Q: How do I get the raw detection results (bounding boxes, confidence scores)?

Check model_output.json in the output directory. This file contains the raw predictions from the layout detection model, including category labels, bounding boxes, and confidence scores for every detected element.

Q: What deep learning models does MinerU use?

Q: Can I disable inline formula masking during OCR?

Yes, set the environment variable:

export MINERU_OCR_DET_MASK_INLINE_FORMULA_ENABLE=false