---
id: mineru
version: "3.4.5"
license: LicenseRef-MinerU-Open-Source-License
license_treatment: unclear
maintenance: active
---

# mineru — A practical document parsing tool for converting PDF, images, DOCX, PPTX, and XLSX into Markdown and JSON

License: unclear · Maintenance: active · Downloads: 335.8K/mo

## What it is and what it does

MinerU is a document parsing engine that reads PDF, DOCX, PPTX, XLSX, images, and web pages and outputs them as structured Markdown or JSON. It uses a dual VLM (vision language model) and OCR engine to handle both text-based and scanned documents, supporting 109 languages and complex layouts like multi-column text, cross-page tables, and handwriting. The package includes native parsers for DOCX, PPTX, and XLSX (as of version 3.1.0), converts formulas to LaTeX and tables to HTML, and reconstructs layout in human reading order with automatic header/footer removal.

The package ships with multiple inference backends: a fast pipeline backend optimized for CPU/GPU, a VLM engine for high accuracy, and a hybrid engine balancing speed and precision. It integrates with LangChain, LlamaIndex, Dify, FastGPT, and other RAG frameworks, and offers CLI, REST API, Python SDK, and MCP Server interfaces. You can deploy it privately and fully offline, with support for domestic AI chips (Ascend, Cambricon, Enflame, and others). The 29 runtime dependencies include heavy libraries like opencv-python, huggingface-hub, and fastapi, so installation expands your environment substantially.

Use it for:

- Ingest PDFs and documents into RAG pipelines by converting them to structured Markdown or JSON for embedding and retrieval.
- Parse scanned or handwritten documents with OCR to extract text and tables in human reading order.
- Convert DOCX, PPTX, and XLSX files to Markdown for version control, archival, or downstream processing.
- Build document understanding workflows for LLM agents that need to reason over complex layouts and multi-language content.
- Extract and reconstruct tables from PDFs as HTML or JSON for data analysis and database ingestion.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts PDF, DOCX, PPTX, XLSX, images, and web pages into structured Markdown or JSON using VLM and OCR engines, supporting 109 languages and complex layouts.

Yes, with conditions. MinerU is actively maintained, has no known vulnerabilities, and offers broad multi-format support with strong accuracy on complex documents. However, the custom license treatment is unclear—verify the terms before commercial use. The 29 runtime dependencies are substantial; assess whether your environment can absorb them. Install if you need reliable document parsing for RAG, LLM workflows, or multi-format ingestion; skip if you need lightweight PDF-only extraction or have strict license requirements.

## Install

pip install mineru
uv add mineru
poetry add mineru

## Installing mineru

Before you install: Low install friction with a pure-Python wheel. Brings 29 runtime dependencies including heavy libraries (opencv-python, huggingface-hub, modelscope, fastapi) that will expand your environment significantly. Active maintenance with recent releases and high repository engagement (77637 stars).

License in practice: Licensed under MinerU Open Source License (LicenseRef-MinerU-Open-Source-License), a custom Apache 2.0–based license. License treatment is marked unclear in the metadata; verify the exact terms at the repository before integrating into proprietary or commercial workflows.

Quickstart:

pip install mineru

from mineru.api import MinerU

api = MinerU()
result = api.parse_pdf('document.pdf')
print(result.to_markdown())

Requires Python 3.10–3.13. First run may download model files (size and time depend on chosen backend). Verify custom license terms before production use.

Verify before relying:

- Whether the custom MinerU Open Source License permits commercial use without restrictions or attribution requirements.
- Whether all 29 runtime dependencies are required for basic parsing or if subsets can be installed for lighter use cases.
- Performance characteristics (latency, throughput, memory) for typical document sizes and batch processing.
- Whether the VLM and OCR engines require model downloads on first run and how much disk space they consume.

## Package facts

- License: LicenseRef-MinerU-Open-Source-License (unclear)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 335.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pdf to markdown conversion, document parsing ocr vlm, extract structured data from documents, multi-format document understanding, docx pptx xlsx parsing, document layout analysis, rag document ingestion, document-parsing, ocr-vlm, rag-ingestion

[View on SkillFed](https://skillfed.io/packages/mineru) · [View on PyPI](https://pypi.org/project/mineru/)