MinerU PDF Parser Tutorial: Convert Documents to Markdown and JSON

opendatalab/MinerU is a document parsing tool for preparing data for large model applications. It can convert inputs such as PDF, images, DOCX, PPTX, and XLSX into Markdown, JSON, and intermediate structured outputs, making them easier to use in RAG, information extraction, knowledge base construction, and Agent workflows.

The problem it addresses is very concrete: real documents often contain multi-column layouts, tables, formulas, headers and footers, scanned pages, handwriting, and image captions. Sending this content directly to a large model can easily produce broken reading order, lost table structure, unreadable formulas, and too much OCR noise. MinerU first parses layout, text, tables, formulas, and OCR content, then outputs results that are closer to both machine-readable data and human reading order.

Quick Answer

MinerU is an open-source document parser that converts PDFs, scans, images, and supported Office files into structured Markdown and JSON. It is most useful for complex layouts, OCR, tables, and formulas before RAG ingestion; for a simple text-only PDF, a lighter extractor may be faster.

What problems it is suited for

MinerU is a good fit for scenarios such as:

Parsing papers, reports, contracts, and manuals into Markdown;
Preparing cleaner document chunks for RAG knowledge bases;
Extracting text, tables, and formulas from scanned PDFs or images;
Converting DOCX, PPTX, and XLSX into structured data that downstream workflows can consume;
Batch-processing documents in a local or private environment;
Preparing data for frameworks such as LangChain, LlamaIndex, Dify, RAGFlow, and FastGPT.

If your task is only to read a simple text-based PDF, a conventional PDF extraction tool may already be enough. MinerU is most valuable when complex layouts, tables, formulas, multiple input formats, or batch document data production start to matter.

Core capabilities

According to the project README, MinerU supports PDF, image, DOCX, PPTX, and XLSX inputs. It can output Markdown, JSON arranged by reading order, and visualization results for checking parsing quality.

Key capabilities include:

Automatically removing headers, footers, footnotes, page numbers, and other distractions;
Outputting text in human reading order for single-column, multi-column, and complex layouts;
Preserving document structure such as headings, paragraphs, and lists;
Extracting images, image captions, tables, table titles, and footnotes;
Recognizing formulas and converting them to LaTeX;
Recognizing tables and converting them to HTML;
Automatically detecting scanned PDFs and garbled PDFs, then enabling OCR;
Supporting OCR for 109 languages;
Providing CLI, FastAPI, Gradio WebUI, and mineru-router.

The 3.1.0 release in April 2026 introduced native parsing for PPTX and XLSX, and upgraded the main VLM model to MinerU2.5-Pro-2604-1.2B. The GitHub release page shows that 3.2.3, released on June 4, 2026, added superscript and subscript detection/output, along with a post-OCR fallback mechanism for handling private-use text.

Installation

For local testing, the official path is to install uv first, then install the full feature package:

1
2
3


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

You can also install from source:

1
2
3


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

mineru[all] includes the core features and is described as compatible with Windows, Linux, and macOS. Document parsing is sensitive to hardware and dependency details, especially GPU support, inference frameworks, Python versions, and system environments. Before production deployment, run a small sample first, then decide whether to move into batch processing.

First document parse

The basic command specifies an input path and output path:

1

mineru -p <input_path> -o <output_path>

If the device does not meet GPU acceleration requirements, specify the pipeline backend to run on a pure CPU path:

1

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

<input_path> can be a single file or a directory. In practice, start with a small directory containing only a few representative documents:

1

mineru -p ./samples -o ./output -b pipeline

This lets you inspect output quality, runtime, memory usage, and file structure before scaling up to a full document library.

How to use the output

MinerU outputs can feed several downstream workflows.

The first is RAG. You can use Markdown as the input for chunking and vectorization, while keeping headings, paragraphs, lists, tables, and formulas as close to the original semantics as possible. Compared with directly OCRing everything into one large text block, structured Markdown is easier to chunk, cite, and trace back.

The second is information extraction. JSON and intermediate results are suitable for downstream scripts, such as extracting tables, formulas, image captions, or specific sections. For automatically organizing reports, papers, or contract fields, this is more stable than working with plain text only.

The third is human review. MinerU provides layout and span visualization results, which help you check whether content was missed, whether the order is reasonable, and whether tables were distorted. Before batch processing, it is best to sample and inspect these visualization outputs.

Backend choices

MinerU documentation mainly mentions several backend paths:

pipeline: good compatibility, runs on CPU or GPU, suitable for first trials and regular batch processing;
vlm-engine: higher accuracy with higher hardware requirements, suitable for complex documents and high-quality parsing;
hybrid-engine: combines native text extraction with high-accuracy parsing, suitable when you want to reduce hallucinations and improve complex layout quality;
*-http-client: connects to OpenAI API-compatible services, including local or remote inference services.

If you only want to validate results, start with pipeline. After you understand your document types, quality requirements, and processing volume, consider VLM or hybrid routes. For enterprise internal documents, backend choice also depends on whether data is allowed to leave the local environment.

Deployment options

MinerU supports CLI, local API, Gradio WebUI, Docker, and mineru-router. Different entry points suit different teams:

Personal testing: CLI is the most direct;
Non-technical users: Gradio WebUI is friendlier;
Integration into existing systems: FastAPI or REST API is a better fit;
Multiple services, multiple GPUs, high concurrency: consider mineru-router;
Lower environment setup cost: Docker is worth looking at on Linux or WSL2.

Docker deployment is currently more suitable for Linux and Windows with WSL2. macOS users usually start with the pip / uv installation route.

How it differs from ordinary OCR tools

Ordinary OCR tools mainly focus on recognizing text from images. That is important, but it is not enough for RAG. RAG also cares about paragraph order, heading hierarchy, table structure, formula expression, image context, and traceability.

MinerU is more like a preprocessing tool for document understanding. It is not just OCR: it also handles layout analysis, reading order, table HTML, formula LaTeX, multi-format input, and structured output. It is better suited for turning complex documents into data that downstream models can consume reliably.

This also means heavier is not always better. For simple invoices, single-page images, or plain text PDFs, lightweight OCR or PDF text extraction may be faster. MinerU is more suitable when document complexity is already clearly affecting downstream results.

Choosing between PaddleOCR, Marker, and Unstructured

These tools overlap, but their entry points are different.

PaddleOCR focuses more on OCR foundations and text recognition components, which is useful when you need to build a finer-grained OCR pipeline yourself. Marker focuses more on PDF-to-Markdown conversion, making it a good fit for quickly turning documents into readable Markdown. Unstructured is closer to document data extraction and enterprise data pipelines, useful for sending multiple document types into search or ETL workflows.

MinerU is oriented toward LLM, RAG, and Agent data preparation. It emphasizes complex layouts, tables, formulas, multi-format input, VLM + OCR dual engines, and private deployment. If your documents are mainly papers, reports, textbooks, PPTs, and spreadsheets, and the downstream target is a large model application, it is worth testing separately.

Batch processing advice

Before formal batch processing, run a small validation in this order:

Select 10 to 20 representative documents, covering scans, complex tables, multi-column papers, PPT, and Excel.
Parse them with the pipeline backend first, recording runtime, memory, output size, and failed samples.
Sample-check Markdown, JSON, and visualization results, focusing on reading order, tables, formulas, and image captions.
For samples with insufficient quality, try VLM or the hybrid backend.
After confirming the output structure, connect it to RAG chunking, vectorization, and citation tracing.

Do not throw the whole document library in at the start. Document parsing failures are often specific: a certain kind of scan, table, font, language direction, or cross-page content. Find the boundaries first, then scale up; it saves a lot of time.

Privacy and compliance

If you are processing internal company documents, customer data, contracts, financial statements, or unpublished research materials, confirm the deployment mode and data flow first.

Pay special attention to:

Whether file content is sent to an external model service;
Whether local inference, remote inference, or an OpenAI API-compatible service is being used;
Whether intermediate files contain full text, images, tables, or sensitive business information;
Whether Markdown / JSON outputs enter logs, object storage, or shared directories;
Whether failed batch samples will be uploaded to issues, communities, or third-party debugging platforms.

MinerU supports private and offline deployment, but that does not mean every configuration is automatically offline. Before real deployment, map the full data path from input files, temporary directories, model inference, and output directories to the logging system.

When not to use it

You can skip MinerU for now in these situations:

The document is simple, and ordinary PDF text extraction is enough;
You only need to read a few pages once and do not need structured output;
The current machine lacks resources, and parsing cost is higher than the benefit;
Document quality is so poor that OCR results require heavy manual correction;
Private documents cannot enter the current inference chain;
The team does not yet have a clear downstream need for RAG, extraction, or a knowledge base.

A document parsing tool should serve a downstream workflow, not exist for parsing alone. If there is no clear consumer, first align output samples with downstream requirements, then decide whether to invest in batch processing.

Troubleshoot MinerU CUDA When the GPU Is Not Used

If your MinerU environment reports something like this after checking PyTorch:

1
2
3
4
5


PyTorch: 2.8.0+cpu
PyTorch CUDA: None
CUDA available: False
GPU count: 0
GPU: 未检测到

You can basically confirm that the current environment has the CPU-only PyTorch build installed, so MinerU will not use the NVIDIA GPU. Even if the machine has an RTX 4060, MinerU can only run on CPU as long as torch in that Python environment is the CPU build.

The fix is straightforward: in the same .venv, replace torch and torchvision with the CUDA build. For PyTorch 2.8.0, the official CUDA 12.8 wheels are available, so you can install the cu128 build directly.

First check the NVIDIA driver

Run this in PowerShell:

1

nvidia-smi

Normally, you should see something like:

1
2
3


NVIDIA GeForce RTX 4060
Driver Version: ...
CUDA Version: 12.x

The CUDA Version shown here is the highest CUDA version supported by the current graphics driver. As long as nvidia-smi can detect the GPU, you usually do not need to install the full CUDA Toolkit separately.

If nvidia-smi cannot detect the GPU at all, do not start with PyTorch. Update or reinstall the NVIDIA driver first.

Enter the virtual environment used by MinerU

Go to the MinerU project directory. Here C:\Work\test is used as an example:

1

cd C:\Work\test

If the project uses .venv, activate it:

1

.\.venv\Scripts\Activate.ps1

Confirm the current Python path:

1

python -c "import sys; print(sys.executable)"

It should point to a path like:

1

C:\Work\test\.venv\Scripts\python.exe

This step matters. You need to replace PyTorch in the Python environment that MinerU actually uses, not the system Python, another Conda environment, or a random interpreter selected by VS Code.

Uninstall the CPU PyTorch build

After confirming that .venv is active, uninstall the current CPU build:

1

uv pip uninstall torch torchvision

If you do not use uv, regular pip can also work, but it is better not to mix tools inside the same environment. This guide continues with uv pip.

Install the CUDA 12.8 PyTorch build

Install the CUDA 12.8 build matching PyTorch 2.8.0:

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

The official version pairing is:

1
2
3


torch 2.8.0
torchvision 0.23.0
CUDA 12.8

The CUDA PyTorch download can be large, often several GB. Be patient if the network is slow.

If uv says the package is already installed but your check still shows the CPU build, force a reinstall:

1

uv pip install --reinstall torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

Verify that CUDA is available

Run:

1

python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA build:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available()); print('GPU count:', torch.cuda.device_count()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else '未检测到')"

The correct result should look like:

1
2
3
4
5


PyTorch: 2.8.0+cu128
CUDA build: 12.8
CUDA available: True
GPU count: 1
GPU: NVIDIA GeForce RTX 4060

The most important line is:

1

CUDA available: True

If it is still False, PyTorch still cannot use CUDA. Common causes include installing into the wrong environment, still having the CPU build of torch, a broken NVIDIA driver, or using a Python interpreter different from MinerU’s .venv.

Run a real GPU computation

Seeing CUDA available: True is useful, but you can also run a real CUDA tensor operation:

1

python -c "import torch; x=torch.randn(4096,4096,device='cuda'); y=x@x; torch.cuda.synchronize(); print('设备:', y.device); print('显存:', round(torch.cuda.memory_allocated()/1024**2,1), 'MB')"

A normal result looks like:

1
2


设备: cuda:0
显存: 128.0 MB

This means PyTorch not only detects the GPU, but can actually run CUDA computation on the RTX 4060.

Watch the GPU while running MinerU

Open a second PowerShell window and monitor the GPU:

1

nvidia-smi -l 1

Then run MinerU in the first window:

1

mineru -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

If the virtual environment is not activated, call the executable inside .venv directly:

1

.\.venv\Scripts\mineru.exe -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

Watch nvidia-smi. If the following signs appear, MinerU is very likely using the RTX 4060:

python.exe appears.
VRAM usage increases.
GPU-Util rises during inference.
VRAM is released after MinerU exits.

How to think about RTX 4060 and MinerU modes

RTX 4060 belongs to NVIDIA’s 40 series, the Ada Lovelace architecture, which is within the hardware range supported by MinerU GPU acceleration. After the correct CUDA PyTorch build is installed, the normal mineru command can use the GPU.

If you explicitly specify:

1

mineru -p "input.pdf" -o "output" -b pipeline

it is more focused on stability and compatibility, and is also suitable for CPU fallback or low-VRAM cases. If you want to use modes such as hybrid-engine or vlm-engine, which depend more on VLM, it is even more important to confirm that CUDA PyTorch is installed correctly.

Common pitfalls

First, installing into the wrong environment. The most common issue is installing CUDA PyTorch into one Python environment while MinerU actually runs in another .venv. Always check:

1

python -c "import sys; print(sys.executable)"

Second, checking only the driver, not PyTorch. A normal nvidia-smi only proves that the driver sees the GPU. It does not prove that PyTorch inside Python supports CUDA. The final check is still:

1

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

Third, confusing CUDA Toolkit with PyTorch CUDA. For most normal use cases, you do not need to install the full CUDA Toolkit separately. If the NVIDIA driver works, installing the official PyTorch CUDA wheel is enough.

Fourth, VRAM may be occupied by other programs. RTX 4060 8GB can run these workloads, but the margin is not huge. Before running MinerU, close games, browser hardware acceleration, other AI inference programs, and software that occupies VRAM.

One-line summary

If you see:

1
2


PyTorch: 2.8.0+cpu
CUDA available: False

then MinerU cannot use the RTX 4060 in the current environment. The correct approach is to uninstall the CPU builds of torch and torchvision in the same .venv, then install:

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

When the verification changes to:

1
2
3


PyTorch: 2.8.0+cu128
CUDA available: True
GPU: NVIDIA GeForce RTX 4060

run MinerU again and use nvidia-smi -l 1 to watch python.exe, VRAM, and GPU utilization. That is how you confirm whether GPU acceleration is really active.

Summary

MinerU is suitable for converting complex documents into Markdown and JSON that large model applications can use more easily. It covers PDF, images, Office documents, tables, formulas, OCR, multilingual recognition, and local deployment, making it especially useful for RAG, knowledge bases, and Agent workflow data preparation.

A steady adoption path is to evaluate quality with an online demo or small local sample, run the workflow with the pipeline backend, and then decide whether to switch to VLM, hybrid, API, or multi-service deployment based on accuracy and throughput requirements. For complex documents, it can significantly reduce preprocessing cost; for simple documents, be careful not to make the workflow heavier than necessary.