This page provides a comprehensive technical guide for installing MinerU, configuring the necessary model assets, and executing your first document conversion. MinerU supports multiple backends (Pipeline, VLM, and Hybrid) and can be deployed across various hardware architectures.
MinerU is distributed via PyPI and can be installed using standard Python package managers like pip or uv. The mineru package provides the core library, CLI tools, and optional extensions for various acceleration engines.
3.10 to 3.13 is required pyproject.toml12MinerU supports modular installation based on the intended use case via optional dependencies pyproject.toml65-118
| Scenario | Command | Description |
|---|---|---|
| Core Functionality | uv pip install "mineru[core]" | Installs core dependencies including vlm, pipeline, and gradio docs/en/quick_start/extension_modules.md9-10 |
| S3 Storage Support | uv pip install "mineru[s3]" | Adds support for reading/writing to S3 buckets docs/en/quick_start/extension_modules.md17-18 |
| VLM Acceleration (vLLM) | uv pip install "mineru[core,vllm]" | Adds vllm for optimized VLM inference (Linux recommended) docs/en/quick_start/extension_modules.md29-30 |
| VLM Acceleration (LMDeploy) | uv pip install "mineru[core,lmdeploy]" | Adds lmdeploy as an alternative VLM acceleration engine docs/en/quick_start/extension_modules.md45-46 |
| Minimal Client | uv pip install mineru | Installs base dependencies for connecting to remote OpenAI-compatible servers docs/en/quick_start/extension_modules.md55-56 |
vllm and lmdeploy provide nearly identical acceleration effects for graphics cards with Volta architecture and later (8GB+ VRAM) docs/en/quick_start/extension_modules.md24-26 It is not recommended to install both simultaneously to avoid conflicts docs/en/quick_start/extension_modules.md40vllm installation requires a CUDA 13.0-compatible driver. For CUDA 12.9 environments, users should follow specific installation paths or use the provided Docker images docs/en/quick_start/extension_modules.md31-33torch and torchvision matching their CUDA version from the official PyTorch website docs/en/usage/quick_usage.md23-25Sources: pyproject.toml12-120 docs/en/quick_start/extension_modules.md6-67 docs/en/quick_start/index.md23-30 docs/en/usage/quick_usage.md23-25
MinerU relies on several specialized deep learning models (layout detection, formula recognition, OCR, etc.). These must be downloaded before the first run.
The mineru-models-download CLI tool (implemented in mineru/cli/models_download.py) automates fetching models from HuggingFace or ModelScope and generates the initial mineru.json configuration mineru/cli/models_download.py129-133
The download tool performs the following steps:
huggingface and modelscope. The auto option detects the best source based on network connectivity mineru/cli/models_download.py18pp_doclayout_v2, unimernet_small, slanet_plus, pp_formulanet_plus_m) and VLM models to a local directory mineru/cli/models_download.py38-51mineru.template.json from GitHub and creates/updates mineru.json, persisting the models-dir paths mineru/cli/models_download.py21-33Diagram: Model Initialization Flow This diagram illustrates how the CLI tool interacts with remote repositories and the local filesystem to prepare the environment.
Sources: mineru/cli/models_download.py13-90 mineru/cli/models_download.py114-155 mineru/utils/models_download_utils.py15-102
mineru.json ConfigurationThe mineru.json file is the central configuration hub. By default, it is located in the user's home directory (~), but can be overridden via the MINERU_TOOLS_CONFIG_JSON environment variable mineru/utils/models_download_utils.py25-28
| Key | Purpose |
|---|---|
models-dir | Local paths for pipeline and vlm model weights mineru/cli/models_download.py26-28 |
config_version | Used by the download tool to determine if the config needs an update (threshold 1.3.2) mineru/utils/models_download_utils.py16 |
llm-aided-config | Configuration for LLM-assisted title hierarchy refinement, supporting OpenAI-compatible APIs mineru/utils/llm_aided.py160-167 |
latex-delimiter-config | Configures LaTeX formula delimiters (defaults to $) docs/en/usage/quick_usage.md126-129 |
Users can update model paths manually in mineru.json if they move the downloaded folders docs/en/usage/quick_usage.md155-158
Sources: mineru/cli/models_download.py21-33 mineru/utils/models_download_utils.py23-29 mineru/utils/llm_aided.py160-188 docs/en/usage/quick_usage.md117-158
The mineru command is the primary entry point for processing local files pyproject.toml129
When a command is executed, the CLI orchestrates the request to specific backends based on the -b flag. If no --api-url is provided, the CLI launches a temporary local mineru-api service docs/en/usage/quick_usage.md18-19
Diagram: CLI Execution and Backend Dispatch Associating CLI commands with internal orchestration logic and backends.
Sources: pyproject.toml128-136 docs/en/usage/quick_usage.md12-14 docs/en/usage/quick_usage.md31-33 docs/en/usage/quick_usage.md15-19
MinerU supports switching between different model repositories to accommodate network conditions.
| Variable | Default | Description |
|---|---|---|
MINERU_MODEL_SOURCE | huggingface | Switch between huggingface, modelscope, or local mineru/cli/models_download.py17-18 |
MINERU_TOOLS_CONFIG_JSON | mineru.json | Custom filename/path for the configuration file mineru/utils/models_download_utils.py25 |
MINERU_API_TASK_RETENTION_SECONDS | 86400 | Retention duration for completed/failed tasks in mineru-api docs/en/usage/quick_usage.md49-50 |
To use ModelScope (recommended for users in China):
To use locally downloaded models (offline mode):
In local mode, the system retrieves the root paths for pipeline and vlm repos from the configuration file mineru/utils/models_download_utils.py11
The utility auto_download_and_get_model_root_path handles the resolution of model IDs based on the selected source and repository mode (pipeline or vlm) mineru/utils/models_download_utils.py102-110
| Mode | Models Downloaded | Repo Configuration |
|---|---|---|
pipeline | Layout, OCR, Formula, Table mineru/cli/models_download.py38-46 | models-dir.pipeline |
vlm | Vision-Language Models mineru/cli/models_download.py57 | models-dir.vlm |
Sources: mineru/cli/models_download.py17-18 mineru/utils/models_download_utils.py11-28 docs/en/usage/quick_usage.md4-7 docs/en/usage/quick_usage.md43-51
Refresh this wiki