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:

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

1. Base image — vLLM or LMDeploy image that supplies Python, CUDA/compute runtime, torch, and the inference engine 1 2
2. System packages — libgl1 (OpenCV), fonts-noto-core, fonts-noto-cjk, fontconfig installed via apt-get 3
3. MinerU package — mineru[core]>=3.4.0 installed with pip, using --break-system-packages because vLLM base images mark their Python environment as externally-managed 4 5
4. Models — mineru-models-download -m all bakes all required models into the image at build time 6
5. Entrypoint — sets MINERU_MODEL_SOURCE=local so MinerU uses the pre-downloaded models rather than fetching them at runtime 7

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

Several accelerators (NPU, MLU, Metax, PPU) support both vLLM and LMDeploy backends, selected at build time via ARG BACKEND=lmdeploy|vllm 15 16.

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 17 18.

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. 19

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 API 18
• vllm>=0.10.1.1,<0.22.0 (optional [vllm] extra, Linux-only) — tracks the supported vLLM range 20
• pypdfium2>=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 21

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 22 23 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.4 and opencv-python==4.11.0.86 explicitly 24 25
• MLU vLLM variant pins transformers==4.50.3 to avoid conflicts with the vendor's torch 26

These are intentional overrides of MinerU's own flexible bounds to ensure compatibility with specific vendor runtime environments.