# 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

```bash
# 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:

```bash
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

```bash
# 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)

```bash
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:

```bash
# 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.

```bash
# 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
```

| Profile | Service | Default Port |
|---------|---------|-------------|
| `openai-server` | VLM inference server | 30000 |
| `api` | FastAPI document parsing | 8000 |
| `router` | Load-balancing router | 8002 |
| `gradio` | Gradio web UI | 7860 |

### 2.4 Verifying the Installation

```bash
# 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.

```json
{
    "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:

| Section | Purpose |
|---------|---------|
| `bucket_info` | S3-compatible storage credentials for remote input/output |
| `latex-delimiter-config` | LaTeX math delimiter style in Markdown output |
| `llm-aided-config` | Optional LLM-assisted title recognition |
| `models-dir` | Custom paths for pipeline and VLM model weights |
| `config_version` | Config schema version |

### 3.2 Essential Environment Variables

These environment variables control runtime behavior without editing config files:

| Variable | Default | Purpose |
|----------|---------|---------|
| `MINERU_MODEL_SOURCE` | `huggingface` | Model download source (`huggingface` or `modelscope`) |
| `MINERU_LOG_LEVEL` | `INFO` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `MINERU_FORMULA_ENABLE` | `true` | Override formula recognition toggle |
| `MINERU_TABLE_ENABLE` | `true` | Override table recognition toggle |
| `MINERU_DEVICE_MODE` | auto-detected | Force a specific compute device |
| `CUDA_VISIBLE_DEVICES` | all GPUs | Restrict which GPUs MinerU uses |
| `MINERU_PDF_RENDER_TIMEOUT` | (varies) | Timeout for PDF page rendering |
| `MINERU_PDF_RENDER_THREADS` | (varies) | Thread count for PDF rendering |
| `FTLANG_CACHE` | (default) | Cache directory for fasttext language detection |

> [!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:

```json
{
    "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:

```json
{
    "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:

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

**Required arguments:**

| Flag | Description |
|------|-------------|
| `-p, --path` | Input file or directory (PDF, image, DOCX, PPTX, XLSX) |
| `-o, --output` | Output directory |

**Common options:**

| Flag | Default | Description |
|------|---------|-------------|
| `-m, --method` | `auto` | Parse method: `auto`, `txt`, `ocr` |
| `-b, --backend` | `hybrid-auto-engine` | Parsing backend (see Section 4.2) |
| `-l, --lang` | `ch` | OCR language hint |
| `-s, --start` | none | Start page (0-based) |
| `-e, --end` | none | End page (0-based) |
| `-f, --formula` | `True` | Enable formula recognition |
| `-t, --table` | `True` | Enable table recognition |
| `--api-url` | none | MinerU FastAPI base URL (omit to start a temp local server) |

**Examples:**

```bash
# 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:

| Backend | How It Works | Best For |
|---------|-------------|----------|
| `pipeline` | Traditional layout detection + OCR + formula/table models | General-purpose; broadest format support |
| `vlm-auto-engine` | Vision-language model on local GPU | High-quality parsing when VLM models are available |
| `vlm-http-client` | VLM via remote OpenAI-compatible server | Offloading VLM inference to a dedicated server |
| `hybrid-auto-engine` | Combines pipeline + VLM locally **(default)** | Best overall quality; requires more VRAM |
| `hybrid-http-client` | Pipeline locally + VLM via remote server | Hybrid quality without local VLM VRAM cost |

```bash
# 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.

| Method | Behavior |
|--------|----------|
| `auto` | Analyzes each page and chooses `txt` or `ocr` automatically **(default)** |
| `txt` | Extracts embedded text directly from the PDF |
| `ocr` | Runs OCR on rendered page images |

```bash
# 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:

```bash
# 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
      ...
```

| File | Description |
|------|-------------|
| `*.md` | The Markdown rendering of the document. Tables become Markdown tables, formulas become LaTeX, images are referenced as `![](images/...)` |
| `content_list.json` | Each content block (paragraph, table, image, formula) with type, text, and bounding box coordinates |
| `model_output.json` | Raw predictions from layout detection, including category labels and confidence scores |
| `images/` | All images extracted from the document, named by page and index |

### 4.6 Using the API Server

#### Starting the Server

```bash
# 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

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/file_parse` | Synchronous file parsing (blocks until complete) |
| `POST` | `/tasks` | Submit an asynchronous parse task |
| `GET` | `/tasks/{task_id}/status` | Poll async task status |
| `GET` | `/tasks/{task_id}/result` | Download completed task result (ZIP) |
| `GET` | `/health` | Health check |

#### Synchronous Parsing

```bash
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:

```bash
# 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

```bash
# 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
```

| Flag | Default | Description |
|------|---------|-------------|
| `--enable-example` | `True` | Show example files in the UI |
| `--enable-http-client` | `False` | Enable remote HTTP client backends |
| `--enable-api` | `True` | Expose Gradio's API endpoints |
| `--max-convert-pages` | `1000` | Maximum pages per conversion |
| `--server-name` | `127.0.0.1` | Bind address |
| `--server-port` | `7860` | Bind port |
| `--api-url` | none | Connect to an existing MinerU API |
| `--enable-vlm-preload` | `False` | Preload VLM models at startup |
| `--latex-delimiters-type` | `all` | LaTeX delimiter rendering style |

### 4.8 Multi-GPU Load Balancing with the Router

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

```bash
# 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
```

| Flag | Default | Description |
|------|---------|-------------|
| `--host` | `127.0.0.1` | Bind address |
| `--port` | `8002` | Bind port |
| `--local-gpus` | `auto` | Local GPU config: `auto`, `none`, or CSV of GPU IDs |
| `--upstream-url` | none | Remote API server URL (repeatable) |
| `--worker-host` | `127.0.0.1` | Host for spawned workers |
| `--enable-vlm-preload` | `False` | Preload VLM models on workers |

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:

```bash
# 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:

```bash
# 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

```bash
mineru -p report.pdf -o ./output
```

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

### 5.2 Batch Convert a Directory of Files

```bash
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

```bash
# 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:

```bash
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.

```bash
# 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.

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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:

```bash
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:

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

### 5.12 Select a Specific GPU

```bash
# 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

```bash
# 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:

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

### 5.14 Change the Model Download Source

```bash
# 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

```bash
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:**
```bash
# 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):
  ```bash
  mineru -p doc.pdf -o out -b pipeline
  ```
- Disable formula or table recognition:
  ```bash
  mineru -p doc.pdf -o out -f false -t false
  ```
- Restrict to a GPU with more VRAM:
  ```bash
  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:**
```bash
# 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](https://github.com/opendatalab/MinerU/issues/4792).

**Solution:**
- Increase the polling timeout in your client code
- For very large documents, parse a page range instead:
  ```bash
  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](https://github.com/opendatalab/MinerU/issues/4008).

**Solution:**
- Try a different backend:
  ```bash
  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](https://github.com/opendatalab/MinerU/issues/4207).

**Solution:**
- Try the VLM backend, which often handles complex tables better:
  ```bash
  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](https://github.com/opendatalab/MinerU/issues/1717).

**Solution:** Adjust the delimiter configuration in `mineru.json`:
```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](https://github.com/opendatalab/MinerU/issues/2551).

**Solution:**
- Use OCR mode instead of text extraction:
  ```bash
  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](https://github.com/opendatalab/MinerU/issues/1367).

**Solution:**
```bash
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](https://github.com/opendatalab/MinerU/issues/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](https://github.com/opendatalab/MinerU/issues/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](https://github.com/opendatalab/MinerU/issues/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:**
```bash
# 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:
  ```bash
  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`:
```bash
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:
```bash
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`:
```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](https://github.com/opendatalab/MinerU/issues/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?**

| Task | Model |
|------|-------|
| Layout detection | DocLayoutV2 (PPDocLayoutV2) |
| OCR | PytorchPaddle (multi-language) |
| Formula recognition | Unimernet / PP FormulaNet Plus M (Chinese) |
| Table (wireless) | SLANet+ |
| Table (wired) | UNet |
| Table classification | PaddleTableCls |
| Page orientation | PaddleOrientationCls |

**Q: Can I disable inline formula masking during OCR?**

Yes, set the environment variable:
```bash
export MINERU_OCR_DET_MASK_INLINE_FORMULA_ENABLE=false
```

---

_Generated May 2026 from opendatalab/MinerU at e88f6d6. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._