Docker Image Architecture#
MinerU's Docker images follow a thin-layer pattern: a vendor-supplied vLLM (or LMDeploy) image provides the full inference stack, and MinerU adds only system fonts, the mineru package, and pre-downloaded models on top.
Image Variants#
MinerU ships 11 Dockerfiles across two directories:
| Path | Purpose |
|---|---|
docker/global/Dockerfile | Standard NVIDIA GPU (x86_64 + AArch64), uses official vLLM images, HuggingFace model source |
docker/china/Dockerfile | Same hardware as global, DaoCloud-mirrored vLLM images, Aliyun pip mirrors, ModelScope model source |
docker/china/{npu,mlu,musa,dcu,gcu,kxpu,corex,maca,ppu}.Dockerfile | Vendor-specific accelerators (Ascend, Cambricon, MooreThreads, Hygon, Enflame, Kunlun, Iluvatar, Metax, T-head) |
The global and china variants are functionally identical; they differ only in which registries are used to pull images and download models — an important distinction for environments without direct access to Docker Hub or HuggingFace.
Build Layers (all variants follow this sequence)#
- Base image — vLLM or LMDeploy image that supplies Python, CUDA/compute runtime, torch, and the inference engine
- System packages —
libgl1(OpenCV),fonts-noto-core,fonts-noto-cjk,fontconfiginstalled viaapt-get - MinerU package —
mineru[core]>=3.4.0installed withpip, using--break-system-packagesbecause vLLM base images mark their Python environment as externally-managed - Models —
mineru-models-download -m allbakes all required models into the image at build time - Entrypoint — sets
MINERU_MODEL_SOURCE=localso MinerU uses the pre-downloaded models rather than fetching them at runtime
Base Image Versions (NVIDIA)#
The standard base image is vllm/vllm-openai:v0.21.0 (CUDA 13.0), with a v0.21.0-cu129 alternative for CUDA 12.9 environments . Both support NVIDIA Compute Capability 7.0–12.1 (Volta through Blackwell) on x86_64 and AArch64.
Accelerator-Specific Base Images#
Hardware-specific Dockerfiles swap in vendor-supplied vLLM ports:
| Accelerator | Base image source | vLLM version |
|---|---|---|
| Ascend NPU | quay.m.daocloud.io/ascend/vllm-ascend | v0.11.0 |
| Hygon DCU | harbor.sourcefind.cn | 0.9.2 |
| Enflame GCU | Aliyun ACR (opendatalab-mineru/gcu) | 0.11 |
| Kunlun XPU | docker.1ms.run/wjie520/vllm_kunlun | v0.10.1.1rc1 |
| Cambricon MLU | Aliyun ACR / opendatalab-mineru | 0.8.3 |
| MooreThreads MUSA | registry.mthreads.com/mcconline | 0.8.4 |
Several accelerators (NPU, MLU, Metax, PPU) support both vLLM and LMDeploy backends, selected at build time via ARG BACKEND=lmdeploy|vllm .
Dependency Conflicts with vLLM Transitive Dependencies#
Because MinerU installs on top of a vLLM image that already has its own dependency tree, pip will often report resolver warnings. The canonical example is lmcache (a vLLM transitive dep) which requires huggingface_hub>=1.5.0 and transformers>=5.4, while MinerU pins huggingface-hub>=0.32.4 and transformers>=4.57.3,<5.0.0 .
These warnings are safe to ignore. lmcache is not used by MinerU at all — it is pulled in solely by the vLLM base image. The versions MinerU installs satisfy MinerU's own requirements; the conflict only appears from lmcache's perspective.
How MinerU manages its own constraints#
MinerU uses explicit upper bounds in pyproject.toml to lock to known-good versions:
transformers>=4.57.3,<5.0.0— keeps transformers on the v4 APIvllm>=0.10.1.1,<0.22.0(optional[vllm]extra, Linux-only) — tracks the supported vLLM rangepypdfium2>=4.30.0,<6.0.0,pdftext>=0.6.3,<0.8.0— upper bounds added after breaking API changes in 5.x and 0.7.0 respectively
When pip emits a dependency conflict warning during a Docker build on a vLLM base image, the practical check is: does the conflict involve a package that MinerU actually imports? If not (as with lmcache), the build is safe. If yes, the issue should be reproduced outside Docker and tracked against pyproject.toml.
--break-system-packages flag#
The Dockerfiles pass --break-system-packages to pip because the vLLM base image's Python environment is marked as externally managed (PEP 668). This flag tells pip to install into it anyway — it is not a sign of a dependency problem, just a way to bypass the system-managed Python guard in the base image.
Explicit version pins in accelerator Dockerfiles#
Some accelerator Dockerfiles go further and pin specific versions of packages that are known to conflict with the vendor's runtime:
- NPU and MLU Dockerfiles pin
numpy==1.26.4andopencv-python==4.11.0.86explicitly - MLU vLLM variant pins
transformers==4.50.3to avoid conflicts with the vendor's torch
These are intentional overrides of MinerU's own flexible bounds to ensure compatibility with specific vendor runtime environments.