MinerU Tutorial: Convert PDF to Markdown for Scientific Papers and Equations

Scientific PDFs are the hardest documents to convert. A single page of a physics or machine learning paper can carry two columns of body text, an inline equation, a displayed equation with a number on the right, a table that spans the column, a figure with a caption, and a footnote. Most converters flatten all of that into a wall of broken text. Equations turn into gibberish. Tables lose their rows. Figures vanish. What you feed your language model is noise.

MinerU is built for exactly this problem. It is an open source tool from the OpenDataLab team that reads a PDF, detects its layout, runs OCR where needed, and emits clean Markdown with LaTeX equations, real Markdown tables, and extracted figures. If your work involves research papers, textbooks, or any document dense with math, MinerU is one of the strongest converters you can run locally.

This tutorial walks through installing MinerU, running your first conversion, understanding the output, tuning it for accuracy, and deciding when it is the right tool versus Marker, PyMuPDF4LLM, or a hosted converter.

What MinerU Actually Does

MinerU is not a single regex pass over a PDF text stream. It is a pipeline of machine learning models that work together:

• Layout detection: A model identifies the reading order and classifies each region as text, title, table, figure, or formula. This is what lets MinerU handle two-column papers correctly instead of reading straight across the page.
• Formula recognition: Detected equations, both inline and displayed, are converted to LaTeX so they survive the trip into Markdown.
• Table recognition: Table regions are parsed into structured rows and columns and rendered as Markdown or HTML tables.
• OCR: For scanned pages or embedded images of text, MinerU runs optical character recognition instead of trusting a text layer that may not exist.

The result is Markdown that keeps the meaning of the original document, not just its words. For anyone building a knowledge base or a retrieval pipeline over academic literature, that structure is the whole point.

Installing MinerU

MinerU is a Python package. It works best in a clean virtual environment on Python 3.10 or newer. Start by isolating it:

python -m venv mineru-env source mineru-env/bin/activate pip install --upgrade pip

Then install MinerU itself. The core package pulls in the models and the command line tool:

pip install "mineru[core]"

On first run, MinerU downloads its model weights. This is a one time step, but the download is large, so expect it to take a few minutes on a normal connection. If you work behind a firewall or want reproducible builds, you can pre-download the models and point MinerU at a local cache. Check the version once the install finishes:

mineru --version

MinerU runs on CPU, but it is meaningfully faster with an NVIDIA GPU and CUDA installed. For a handful of papers, CPU is fine. For a batch of hundreds, a GPU turns hours into minutes. If you have one, install the CUDA build of PyTorch before installing MinerU so it detects the accelerator automatically.

Your First Conversion

The command line interface is the fastest way to get output. Point it at a PDF and give it an output directory:

mineru -p paper.pdf -o ./output

MinerU processes the file and writes results into a subfolder named after your document. Inside you will find several artifacts:

• A .md file: the clean Markdown you came for.
• An images folder: every figure and extracted image, referenced from the Markdown.
• A layout or content JSON file: the structured intermediate result, useful if you want to post-process programmatically.
• Visualization PDFs: overlays that show what the layout model detected, which are invaluable when you are debugging a bad conversion.

Open the Markdown and you will see headings mapped to # levels, displayed equations wrapped in LaTeX delimiters, tables rendered as pipe-delimited Markdown, and figures linked with standard image syntax. This is output you can drop straight into a notebook, a docs site, or a vector store.

Reading the Markdown Output

The detail that sets MinerU apart is how it handles math. A displayed equation comes out as LaTeX between block delimiters, and inline math stays inline. That means a downstream tool that understands LaTeX, from a Markdown renderer with a math plugin to a language model, can reason about the actual formula rather than a mangled approximation.

Tables are the second win. Where a naive text extractor collapses a table into a run-on line, MinerU preserves the grid. Complex tables with merged cells sometimes come out as HTML tables embedded in the Markdown, which is valid and keeps the structure intact even when a plain Markdown table cannot express the layout.

Figures are extracted as image files and referenced from the Markdown, so a chart or diagram is not silently dropped. You still lose the semantic content of the image itself unless you add a captioning step, but the figure and its caption text stay connected in the document flow.

Tuning MinerU for Better Accuracy

Default settings handle most modern, digitally-produced PDFs well. When you hit a difficult document, a few options make a real difference.

Choose the right parsing method

MinerU can operate in different modes depending on whether the PDF has a reliable text layer. For a born-digital PDF, the text extraction path is fast and accurate. For a scanned document, you want the OCR path so MinerU reads the pixels instead of a missing or garbled text layer. You can force OCR when you know a file is scanned:

mineru -p scanned-paper.pdf -o ./output -m ocr

If you are not sure, the automatic mode inspects each page and picks the right approach. Forcing OCR on a clean digital PDF is slower and occasionally less accurate, so only reach for it when the text layer is genuinely bad. For a broader treatment of scanned documents, see our guide on converting scanned and image PDFs with OCR.

Set the language for OCR

OCR accuracy improves when the model knows what language it is reading. If your papers are not in English, pass the language hint so the recognizer loads the right model. This matters most for non-Latin scripts, where the default English model will struggle.

Check the visualization output

When a conversion looks wrong, do not guess. Open the layout visualization PDF that MinerU produces. It draws boxes around every region it detected and labels them. If a two-column page is being read across instead of down, or a table is being classified as plain text, you will see it immediately. That tells you whether the problem is layout detection, OCR, or something in your own post-processing.

Using MinerU from Python

The command line is convenient, but for pipelines you will want to call MinerU from code. The package exposes an API you can wire into a batch job or a service. A typical pattern reads a PDF, runs the pipeline, and writes the Markdown and images to disk, which you can then chunk and embed. If you are feeding a retrieval system, this is where MinerU output shines, because clean structure produces clean chunks. Our write-up on building better RAG pipelines with clean Markdown explains why that structure lifts retrieval accuracy.

A batch loop over a folder of PDFs looks roughly like this at the shell level, which is often all you need:

for pdf in papers/*.pdf; do mineru -p "$pdf" -o ./output done

Note the quoted variable so filenames with spaces do not break the loop. For serious batch work on a GPU box, process files in parallel up to the limit of your VRAM, and monitor memory, since the models are not small.

How MinerU Compares to Marker and PyMuPDF4LLM

MinerU is not the only local converter, and it is not always the right one. Here is how it stacks up against the two tools it is most often compared with.

PyMuPDF4LLM is the speed champion. If your PDFs are born-digital and mostly text and simple tables, it converts in milliseconds with almost no setup, and it does not need a GPU. It does not do serious equation recognition, so it is the wrong pick for a math-heavy paper.

Marker sits in the middle. It is fast, handles a wide range of documents, and produces solid Markdown with reasonable equation support. It is a great default when you have mixed content and want good results quickly.

MinerU wins when the document is genuinely hard: dense equations, multi-column academic layouts, and tables that other tools mangle. The cost is a heavier install and slower per-page processing. Choose it when accuracy on scientific content matters more than raw speed. For a wider survey of options, our roundup of the best PDF to Markdown converters puts these tools in context alongside hosted services.

When a Hosted Converter Makes More Sense

Running MinerU locally is the right call when you are processing sensitive data, working at large scale, or want full control over the pipeline. But it is real infrastructure. You maintain a Python environment, manage model downloads, and ideally provision a GPU. For an occasional paper, or for a non-technical teammate, that is a lot of overhead.

That is where a hosted converter fits. With PDFtoMD you upload a PDF and get clean Markdown back in seconds, with no install, no environment, and no GPU. The free tier gives you 3 conversions per month with no credit card required, which is enough to test whether the output suits your workflow before you commit to running anything yourself. Many teams use a hosted converter for quick one-off jobs and reserve a local MinerU pipeline for large batch runs. See the use cases for where each approach fits, and our guide for researchers converting papers and notes for the academic workflow specifically.

Frequently Asked Questions

Is MinerU free?

Yes. MinerU is open source and free to use, including for the model weights it downloads. Your only cost is the compute you run it on. If you want to avoid managing that compute, a hosted converter like PDFtoMD offers a free tier so you can convert without any local setup.

Do I need a GPU to run MinerU?

No, MinerU runs on CPU. But a CUDA-capable NVIDIA GPU speeds it up substantially, which matters when you process many documents. For a few papers at a time, CPU is perfectly usable.

How well does MinerU handle equations?

Equation handling is MinerU's standout feature. It detects inline and displayed formulas and converts them to LaTeX, so the math survives into Markdown and can be rendered or reasoned over downstream. This is the main reason to pick it over lighter tools for scientific content.

Can MinerU convert scanned PDFs?

Yes. MinerU includes OCR, so it reads scanned pages and images of text rather than relying on a text layer that may be missing. Force OCR mode when you know a file is scanned, or let automatic mode decide per page.

What does MinerU output look like?

You get a Markdown file with proper headings, LaTeX equations, Markdown or HTML tables, and linked figure images, plus a JSON intermediate and layout visualizations. The Markdown is ready for docs sites, notebooks, or a vector store with little or no cleanup.

The Takeaway

MinerU is the tool to reach for when your PDFs are dense with math and structure and you need Markdown that preserves both. It costs you a heavier install and slower processing than lightweight converters, but it repays that with LaTeX equations, real tables, and extracted figures that other tools lose. For clean digital PDFs, PyMuPDF4LLM is faster and Marker is a fine all-rounder, so match the tool to the document.

If you would rather skip the setup entirely, upload your PDF to PDFtoMD and get clean Markdown back in seconds. Whichever path you choose, the goal is the same: turn a hard-to-read PDF into structured Markdown your tools and your models can actually use.