MinerU: Turn PDFs and Office Files into Clean Markdown (GitHub, Scanned)

MinerU takes the documents language models struggle with, such as scanned PDFs, academic papers full of formulas and tables, slide decks and spreadsheets, and turns them into clean Markdown, HTML, LaTeX, DOCX or structured JSON. It reads PDF, images, Word, PowerPoint, Excel, RTF, OpenDocument, EPUB, OFD, HTML and CSV, and keeps layout, reading order, tables and equations instead of flattening them into a wall of text.

Version 4 adds four parsing tiers, from a fast Flash pass for previews and indexing up to Standard and Advanced tiers that run a vision language model for hard layouts. It also keeps a local document library: parse once, then search, read page by page and cite blocks by a stable locator, which is what makes it useful as the document reader inside an agent. There is a Python SDK, an HTTP API, a batch CLI and a Gradio web UI.

The limits: the better tiers want a GPU (the default install runs small models on CPU and the VLM through llama.cpp in Vulkan mode), Docker images for non-NVIDIA hardware were still being updated when scanned, and the licence is Apache 2.0 with extra conditions rather than plain Apache. With about 82,500 stars it is one of the most used open document parsers.

• Repository: github.com/opendatalab/MinerU
• Licence: custom (Other)
• Language: Python. Stars: 82.5K. Forks: 6,815. Last push: Oct 26, 2026.
• Scan: safe, Oct 26, 2026, commit b7f3dd0

Who it is for

Developers building retrieval or agent pipelines over PDFs and Office files, researchers converting papers with formulas and tables, and anyone who needs scanned documents turned into text without uploading them to a cloud service.

Getting started

1. Create and activate a Python environment (Windows: .\.mineru\Scripts\Activate.ps1)

uv venv .mineru --python 3.12 && source .mineru/bin/activate

2. Install MinerU 4

uv pip install -U "mineru>=4.0,<5"

3. Convert a document to Markdown

mineru-kit parse document.pdf -o document.md --tier standard

Run mineru-kit webui for a browser interface. With an NVIDIA GPU, install mineru[full] instead for much faster parsing. Documents stay on your machine unless you add --remote, which sends them to the official mineru.net service.

Safety scan

We cloned opendatalab/MinerU at commit b7f3dd0 on Oct 26, 2026 and ran the checks described on the GitHub Tools page: credential patterns, decode-and-execute code, install-time scripts, committed binaries, risky CI workflows, every host the code talks to, known vulnerabilities in pinned dependencies, and project hygiene. A person read every hit. This is what we found.

• No secrets, no suspicious code patterns, no install hooks, no committed binaries and no bare-IP URLs across roughly 128,000 lines of Python.
• MinerU has built-in telemetry: aggregated counts of commands, tiers, success rates and timing buckets, documented as never including document contents, file names, paths or queries. In this release it sends unless consent is explicitly disabled; run mineru telemetry disable to stop it and delete what is queued, or mineru telemetry preview to see the payload.
• The outside hosts are mostly test placeholders. mineru.net is the official hosted parser, used only with --remote. dashscope.aliyuncs.com is the default address for optional LLM-assisted post-processing, which does nothing without an API key you supply. mirrors.aliyun.com appears only in the Dockerfiles under docker/china.
• The advisory lookup only had docs/requirements.txt to check (5 packages, no advisories); the package's own dependencies are declared without a lockfile, so they were not looked up.
• Six workflows. cla.yml uses pull_request_target to run the CLA Assistant bot, which does not check out pull request code. 1 of 6 third-party actions is pinned to a commit. Security policy and licence present; no Dependabot or CodeQL.

What the scanner counted

The raw findings

Every hit the scanner wrote out, with a link to the exact line at the scanned commit. Secrets candidates are redacted.

By the numbers

Lines by language: Python 128.6K, JSON 74.5K, Markdown 42.8K, JavaScript 2,596, YAML 1,215, CSS 494.

Questions

Is MinerU free?

Yes for almost everyone. MinerU uses its own MinerU Open Source License: Apache 2.0 plus extra terms. Commercial use is allowed, but organizations with more than 100 million monthly active users or more than USD 20 million monthly revenue need a separate licence, and anyone offering an online service built on MinerU must say so publicly.

Does MinerU upload my documents?

Not by default. Parsing runs locally, and a document goes to the mineru.net service only when you pass --remote. Separately, the CLI sends anonymous usage telemetry without document contents; mineru telemetry disable turns it off.

Do I need a GPU to run MinerU?

No. The default install runs its small models on the CPU and the vision model through llama.cpp, which works on most machines. An NVIDIA GPU with the mineru[full] install is much faster for the Standard and Advanced tiers on long or complex documents.

This post is part of GitHub Tools, where every repository is cloned and scanned before it is written up. The scan is a snapshot of one commit on one day; the repository has moved on since, so check it before you install.