How to Build and Install MinerU From Source: A Complete Developer Guide

You can build and install MinerU from source by cloning the opendatalab/MinerU repository, creating a Python 3.10–3.13 virtual environment with uv, and running uv pip install -U "mineru[all]" to install the package with all optional dependencies.

MinerU is a Python-based document-parsing toolkit that transforms PDFs and images into machine-readable Markdown or JSON formats. Building from source gives you access to the latest features, all parsing backends, and the ability to modify the core parsing engines. This guide walks through the complete installation process using the actual source structure found in the repository.

Prerequisites and Environment Setup

MinerU requires Python 3.10 through 3.13 according to the version constraints defined in pyproject.toml. While standard pip works, the maintainers recommend using uv for fast dependency resolution and virtual environment management.

Before starting, ensure you have Git installed to clone the repository and sufficient disk space for the optional AI models and dependencies.

Step-by-Step Source Installation

Follow these steps to install MinerU in editable mode with full backend support.

Clone the Repository

Fetch the complete source tree including optional sub-modules for VLM backends:

git clone https://github.com/opendatalab/MinerU.git
cd MinerU

Create an Isolated Python Environment

Use uv to create a virtual environment in the project root:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

This creates a .venv directory containing an isolated Python interpreter that prevents conflicts with system packages.

Install in Editable Mode with All Features

Install the package using the -e .[all] flag to pull every optional dependency group defined in pyproject.toml:

uv pip install -U "mineru[all]"

The [all] extra includes dependencies for the pipeline, VLM, Docker, Gradio, and API backends, ensuring the CLI can access any parsing engine out-of-the-box.

Verify the Installation

Check that the command-line interface is working and view the version defined in mineru/version.py:

mineru --version

You should see output like mineru X.Y.Z, confirming that mineru/cli/client.py is correctly handling the --version flag.

Understanding the Architecture

MinerU organizes its codebase into three logical layers that work together during the build process:

• CLI / API Layer: User-facing entry points including the command line (mineru/cli/client.py), FastAPI server (mineru/cli/fast_api.py), and Gradio web interface (mineru/cli/gradio_app.py)
• Backend Dispatch Layer: Handles device selection and VRAM management through mineru/utils/config_reader.py and mineru/utils/model_utils.py
• Parsing Engines: Core OCR, layout analysis, and extraction logic located in mineru/model/ and various mineru/utils/pdf_*.py utilities

When you install from source, pyproject.toml declares these relationships through optional dependency groups, allowing you to install only the components you need.

Backend Selection and Device Management

After installation, MinerU automatically detects your hardware capabilities. The mineru/utils/config_reader.py module contains get_device() logic that selects between cpu, cuda, npu, or mps (Apple Silicon) based on availability.

For GPU environments, mineru/utils/model_utils.py provides get_vram() to query available video memory. You can constrain this manually when parsing:

mineru -p document.pdf -o ./output -b hybrid-auto-engine --vram 8192

This sets the MINERU_VIRTUAL_VRAM_SIZE environment variable to limit GPU consumption to 8 GB.

Working with Optional Dependencies

The pyproject.toml file defines several extras groups for different use cases. While [all] installs everything, you can optimize your environment by selecting specific extras.

Minimal Pipeline Installation

For CPU-only environments requiring only the lightweight parsing pipeline:

uv pip install -e ".[pipeline]"

VLM-Accelerated Installation

For Linux systems with GPU support wanting VLM acceleration:

uv pip install -e ".[vllm]"

Other available extras include [lmdeploy], [mlx] for Apple Silicon, [api] for FastAPI dependencies, and [gradio] for the web interface.

Testing Your Build

Once installed, test the complete workflow by parsing a sample PDF:

# Basic pipeline backend (CPU-friendly)

mineru -p examples/sample.pdf -o ./output -b pipeline

# Hybrid auto-engine (uses GPU/Apple Silicon if available)

mineru -p examples/sample.pdf -o ./output -b hybrid-auto-engine

To test the VLM HTTP client backend against a remote server:

mineru -p document.pdf -o output_dir -b vlm-http-client --url http://127.0.0.1:30000

Launch the Gradio web UI to verify the [gradio] extras installed correctly:

mineru-gradio

This starts a local server at http://127.0.0.1:7860 using the logic in mineru/cli/gradio_app.py.

Summary

• Clone the opendatalab/MinerU repository and navigate to the project root
• Use Python 3.10–3.13 with uv for fastest dependency resolution
• Install with uv pip install -U "mineru[all]" to get all backends and features
• Verify using mineru --version which reads from mineru/version.py
• Configure device selection through mineru/utils/config_reader.py and VRAM limits via mineru/utils/model_utils.py
• Access different parsing backends (pipeline, hybrid, VLM) through the unified CLI in mineru/cli/client.py

Frequently Asked Questions

What Python versions does MinerU support?

MinerU supports Python 3.10, 3.11, 3.12, and 3.13 as specified in the requires-python field of pyproject.toml. Using versions outside this range will cause the installation to fail with a dependency resolution error.

How do I install only specific parsing backends?

Instead of [all], specify the exact extra you need in the pip install command. Use [pipeline] for the lightweight CPU backend, [vllm] for Linux GPU acceleration, or [mlx] for Apple Silicon optimization. The mineru/cli/client.py entry point will only list available backends corresponding to your installed extras.

Where is the CLI entry point defined?

The main mineru command is implemented in mineru/cli/client.py, which uses Click for argument parsing imported from mineru/utils/cli_parser.py. This file handles the -p (pdf path), -o (output), and -b (backend) flags, sets environment variables like MINERU_DEVICE_MODE, and calls do_parse() to execute the parsing workflow.

Can I limit GPU memory usage during parsing?

Yes. Pass the --vram flag followed by the memory limit in megabytes (e.g., --vram 8192 for 8 GB). This value is processed by mineru/utils/model_utils.py through the get_vram() function and sets MINERU_VIRTUAL_VRAM_SIZE to prevent the parsing engine from exceeding your GPU capacity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}