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

> Build and install MinerU from source with our developer guide. Clone the opendatalab/MinerU repo, set up a Python 3.10–3.13 virtual environment, and install MinerU using uv pip.

- Repository: [OpenDataLab/MinerU](https://github.com/opendatalab/mineru)
- Tags: how-to-guide
- Published: 2026-02-22

---

**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`](https://github.com/opendatalab/MinerU/blob/main/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:

```bash
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:

```bash
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`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml):

```bash
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`](https://github.com/opendatalab/MinerU/blob/main/mineru/version.py):

```bash
mineru --version

```

You should see output like `mineru X.Y.Z`, confirming that [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py)), FastAPI server ([`mineru/cli/fast_api.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/fast_api.py)), and Gradio web interface ([`mineru/cli/gradio_app.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/gradio_app.py))
- **Backend Dispatch Layer**: Handles device selection and VRAM management through [`mineru/utils/config_reader.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py) and [`mineru/utils/model_utils.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/model_utils.py) provides `get_vram()` to query available video memory. You can constrain this manually when parsing:

```bash
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`](https://github.com/opendatalab/MinerU/blob/main/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:

```bash
uv pip install -e ".[pipeline]"

```

### VLM-Accelerated Installation

For Linux systems with GPU support wanting VLM acceleration:

```bash
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:

```bash

# 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:

```bash
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:

```bash
mineru-gradio

```

This starts a local server at `http://127.0.0.1:7860` using the logic in [`mineru/cli/gradio_app.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/mineru/version.py)
- **Configure** device selection through [`mineru/utils/config_reader.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py) and VRAM limits via [`mineru/utils/model_utils.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/model_utils.py)
- **Access** different parsing backends (pipeline, hybrid, VLM) through the unified CLI in [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py), which uses Click for argument parsing imported from [`mineru/utils/cli_parser.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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.