How to Install MinerU Using pip: Complete Installation Guide

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.

# Upgrade pip first

pip install --upgrade pip

# Install MinerU with all backends

pip install "mineru[all]"

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

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:

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

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.

Verifying Your Installation

After installation, verify that the CLI is correctly registered by checking the entry point defined in pyproject.toml:

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, which parses arguments using utilities from 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:

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

Force OCR-only mode for scanned documents:

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

Use lightweight CPU-only pipeline:

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

Behind the scenes, 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, 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.
• Configuration: Device selection and VRAM detection are handled by mineru/utils/config_reader.py and 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—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 or other modules to take effect immediately without reinstallation. The entry point in pyproject.toml will point to your local 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 as mineru = mineru.cli.client:main. When you type mineru in your terminal, Python executes the main() function located in mineru/cli/client.py, which coordinates argument parsing via mineru/utils/cli_parser.py and dispatches to the parsing pipeline through do_parse.

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