# How to Install MinerU Using pip: Complete Installation Guide

> Easily install MinerU using pip. Get the full package with all optional backends by running pip install mineru[all] or install the lightweight core only with pip install mineru. Follow our complete installation guide.

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

---

**Install MinerU using pip by running `pip install "mineru[all]"` to get the full package with all optional parsing backends, or `pip install mineru` for the lightweight core only.**

MinerU is an open-source PDF parsing toolkit developed by the OpenDataLab team, distributed as a standard Python package on PyPI. Installing MinerU using pip gives you access to a powerful command-line interface for converting PDFs to Markdown, JSON, and other structured formats.

## Quick Start: Installing MinerU from PyPI

The fastest way to install MinerU depends on whether you need the full suite of machine learning backends or just the core functionality.

### Install with All Optional Dependencies (Recommended)

For most users, installing the `[all]` extra is recommended. This pulls in every optional dependency required for different parsing backends including **torch**, **vllm**, **lmdeploy**, and **mlx-vlm** as defined in the `project.optional-dependencies` section of [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml).

```bash

# Upgrade pip first

pip install --upgrade pip

# Install MinerU with all backends

pip install "mineru[all]"

```

Alternatively, use **uv** for faster, dependency-aware installation:

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

```

### Lightweight Installation (Core Only)

If you only need the core CLI without heavy model dependencies—for example, to call an OpenAI-compatible API or run CPU-only pipelines—install the minimal package:

```bash
pip install mineru

```

This installs only the essential libraries (click, loguru, pdfminer, etc.) defined in the core dependencies, avoiding unnecessary binary wheels on machines without GPU support.

## Installation Methods Explained

MinerU uses optional dependency groups declared in [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml) to manage its modular architecture. The **`[all]`** extra aggregates every optional group (`vlm`, `vllm`, `lmdeploy`, `pipeline`, etc.), allowing you to select exactly what your hardware supports.

**Why use optional extras?** Heavy frameworks like PyTorch and CUDA-specific libraries are declared as optional to prevent installation failures on systems lacking the required hardware. The [`mineru/utils/model_utils.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/model_utils.py) file handles dynamic backend loading based on which dependencies are available.

## Installing from Source (Development Mode)

To modify MinerU or test the latest unreleased features, clone the repository and perform an editable installation:

```bash
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
pip install -e ".[all]"

```

The `-e` (editable) flag creates a direct link to the source tree, ensuring that `import mineru` always reflects your current files without reinstallation. This setup reads the entry point `mineru = mineru.cli.client:main` directly from the local [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml).

## Verifying Your Installation

After installation, verify that the CLI is correctly registered by checking the entry point defined in [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml):

```bash
mineru --help        # Displays CLI help

mineru -V            # Shows installed version from mineru/version.py

```

Both commands invoke the `main` function in [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py), which parses arguments using utilities from [`mineru/utils/cli_parser.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/cli_parser.py) and dispatches to the appropriate parsing backend.

## Basic Usage Examples

Once you have installed MinerU using pip, parse PDFs immediately:

**Parse with automatic backend detection:**

```bash
mineru -p path/to/document.pdf -o ./output

```

**Force OCR-only mode for scanned documents:**

```bash
mineru -p scanned.pdf -o ./output -m ocr

```

**Use lightweight CPU-only pipeline:**

```bash
mineru -p doc.pdf -o ./out -b pipeline

```

Behind the scenes, [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) handles argument parsing, detects file types via `guess_suffix_by_path`, selects devices using `get_device` and `get_vram` from [`mineru/utils/config_reader.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py), and executes `do_parse` with your selected backend.

## Summary

- **Standard installation:** Run `pip install "mineru[all]"` to get MinerU with every optional backend (PyTorch, vLLM, LMDeploy, etc.).
- **Minimal installation:** Run `pip install mineru` for the core CLI without heavy ML dependencies.
- **Fast installation:** Use `uv pip install "mineru[all]"` for significantly faster dependency resolution.
- **Development setup:** Use `pip install -e ".[all]"` in a cloned repository to work with the latest source code.
- **Entry point:** The CLI command `mineru` maps to `mineru.cli.client:main` as declared in [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml).
- **Configuration:** Device selection and VRAM detection are handled by [`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).

## Frequently Asked Questions

### What is the difference between `pip install mineru` and `pip install "mineru[all]"`?

The command `pip install mineru` installs only the core package with essential dependencies like click and pdfminer, suitable for API clients or remote processing. The `pip install "mineru[all]"` command installs the full distribution including all optional extras defined in [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml)—specifically the machine learning backends (torch, vllm, lmdeploy, mlx-vlm) required for local GPU-accelerated parsing.

### Can I use uv instead of pip to install MinerU?

Yes. MinerU supports installation via **uv**, a Rust-based Python package installer. Run `pip install uv` followed by `uv pip install -U "mineru[all]"` for faster resolution and installation of the dependency tree. Uv is particularly effective when installing the heavy `[all]` extra containing PyTorch and CUDA libraries.

### How do I install MinerU for development or contribute to the source code?

Clone the repository from GitHub, navigate to the project root, and run `pip install -e ".[all]"`. This editable installation links the package to your source directory, allowing changes to [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) or other modules to take effect immediately without reinstallation. The entry point in [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml) will point to your local [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) file.

### Where is the CLI entry point defined in the MinerU source code?

The CLI entry point is defined in the `[project.scripts]` section of [`pyproject.toml`](https://github.com/opendatalab/MinerU/blob/main/pyproject.toml) as `mineru = mineru.cli.client:main`. When you type `mineru` in your terminal, Python executes the `main()` function located in [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py), which coordinates argument parsing via [`mineru/utils/cli_parser.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/cli_parser.py) and dispatches to the parsing pipeline through `do_parse`.