I'm building an AI education project. I need to convert PDFs into Markdown, extract images from pages, and preserve math formulas as LaTeX. Most tools I tried choke on the formulas or lose the images. Many require uploading to someone else's server. MinerU does all three and runs on my machine. Nothing gets uploaded anywhere.

What It Does

  • Converts PDF, DOCX, PPTX, XLSX, and images into Markdown or structured JSON
  • Turns math formulas into LaTeX, tables into HTML
  • Extracts images from documents with their positions preserved
  • OCR support for 109 languages, handles scanned pages, handwriting, multi-column layouts
  • Runs offline on CPU or GPU (Apple Silicon MPS works)
  • Licensed under a custom Apache 2.0-based open source license

Formulas come out as real LaTeX, not garbled text. Tables keep their structure. Images land as separate files referenced in the Markdown.

Install

One command:

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

First run downloads models (~10GB). After that, everything is local.

Usage (CLI)

mineru -p test.pdf -o ./output --return_images true

--return_images true pulls all images out of the PDF as separate files. The Markdown references them with relative paths.

For CPU-only machines, add -b pipeline:

mineru -p test.pdf -o ./output -b pipeline --return_images true

Output:

output/
└── document/
    ├── document.md          # Markdown
    ├── images/              # extracted images
    └── document_content_list.json

Web UI (Gradio)

MinerU also has a browser interface. Start the API server first, then launch Gradio.

Terminal 1 (keep running):

cd mineru
source .venv/bin/activate
export NO_PROXY=127.0.0.1,localhost
mineru-api --host 127.0.0.1 --port 8000

Terminal 2:

cd mineru
source .venv/bin/activate
export NO_PROXY=127.0.0.1,localhost
mineru-gradio --server-name 127.0.0.1 --server-port 8808 --api-url http://127.0.0.1:8000

Open http://127.0.0.1:8808, upload a PDF, hit convert, done.

MCP Server

MinerU ships an MCP server. You can hook it into Claude Desktop or Cursor and parse documents from your AI coding workflow. Details in their docs.

Demo

I feed a math-heavy PDF in, Markdown with LaTeX and extracted images comes out.