windoze/mineru repository overview

⁠MinerU

Multi-arch (amd64 + arm64) Docker images for MinerU⁠ — a high-accuracy document parsing engine for LLM / RAG / Agent workflows — with all models pre-baked for fully offline use.

MinerU converts PDF, DOCX, PPTX, XLSX and images into structured Markdown / JSON: formulas → LaTeX, tables → HTML, reading-order reconstruction, 109-language OCR, VLM + OCR dual engine.

This image is built from the official MinerU Dockerfile⁠ with two differences worth knowing about:

• Models are already inside the image. mineru-models-download -s huggingface -m all runs at build time and MINERU_MODEL_SOURCE=local is exported by the entrypoint, so containers start parsing immediately — no first-run download, no HuggingFace access, no model volume to mount.
• Both linux/amd64 and linux/arm64 are published as a single manifest list, so docker pull does the right thing on x86 servers and on ARM (Grace, GB200, Ampere Altra + GPU, …).

⁠Quick reference

• Source Dockerfile / CI: github.com/windoze/mineru-docker⁠
• Upstream project: opendatalab/MinerU⁠ · docs⁠
• Mirror: ghcr.io/windoze/mineru (identical digests)
• Base image: vllm/vllm-openai:v0.21.0 (CUDA 13.0)
• MinerU version: mineru[core] >= 3.4.0
• Architectures: linux/amd64, linux/arm64
• Image size: ~12 GB compressed (models included)

⁠Supported tags

⁠Requirements

• NVIDIA GPU, Volta or newer (compute capability 7.0–12.1), 8 GB+ free VRAM for the vLLM/VLM backends
• Host driver compatible with CUDA 13.0 — check with nvidia-smi
• NVIDIA Container Toolkit⁠ installed
• Linux, or Windows with WSL2. Not for macOS — Docker on macOS cannot reach MPS/MLX, so Apple Silicon gets no acceleration
• The pipeline backend also runs CPU-only, if you have no GPU

⁠Usage

⁠Interactive shell

docker run --gpus all --shm-size 32g --ipc=host \
  -p 30000:30000 -p 8000:8000 -p 8002:8002 -p 7860:7860 \
  -v "$PWD:/work" -w /work \
  -it windoze/mineru:latest /bin/bash

Then, inside the container:

mineru -p input.pdf -o output/                  # default backend
mineru -p input.pdf -o output/ -b pipeline      # fast, stable, CPU-capable
mineru -p input.pdf -o output/ -b vlm-vllm-engine  # highest accuracy, needs GPU

⁠One-shot parse

The entrypoint execs whatever you pass, so you can skip the shell entirely:

docker run --rm --gpus all --shm-size 32g --ipc=host \
  -v "$PWD:/work" -w /work \
  windoze/mineru:latest \
  mineru -p input.pdf -o output/

⁠REST API server (port 8000)

docker run -d --name mineru-api --gpus all --shm-size 32g --ipc=host \
  -p 8000:8000 \
  windoze/mineru:latest \
  mineru-api --host 0.0.0.0 --port 8000

OpenAPI docs at http://<host>:8000/docs. POST /file_parse for synchronous parsing, POST /tasks for async jobs.

⁠Gradio WebUI (port 7860)

docker run -d --name mineru-gradio --gpus all --shm-size 32g --ipc=host \
  -p 7860:7860 \
  windoze/mineru:latest \
  mineru-gradio --server-name 0.0.0.0 --server-port 7860

⁠OpenAI-compatible VLM server (port 30000)

Run the GPU-heavy VLM once, then point any number of thin CPU-only clients at it:

docker run -d --name mineru-openai-server --gpus all --shm-size 32g --ipc=host \
  -p 30000:30000 \
  windoze/mineru:latest \
  mineru-openai-server --host 0.0.0.0 --port 30000

# From anywhere — no GPU, no vLLM needed on this side
mineru -p input.pdf -o output/ -b vlm-http-client -u http://<server-ip>:30000

⁠Router / multi-GPU (port 8002)

docker run -d --name mineru-router --gpus all --shm-size 32g --ipc=host \
  -p 8002:8002 \
  windoze/mineru:latest \
  mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

Unified entrypoint at http://<host>:8002/docs. Use --local-gpus none --upstream-url http://… to aggregate existing mineru-api instances instead of spawning local workers.

⁠Docker Compose

The upstream compose.yaml⁠ works as-is — just point image: at windoze/mineru:latest:

curl -O https://raw.githubusercontent.com/opendatalab/MinerU/master/docker/compose.yaml
sed -i 's|image: mineru:latest|image: windoze/mineru:latest|' compose.yaml

docker compose --profile api up -d            # REST API      :8000
docker compose --profile gradio up -d         # WebUI         :7860
docker compose --profile openai-server up -d  # VLM server    :30000
docker compose --profile router up -d         # Router        :8002

⁠Notes & tuning

• --shm-size and --ipc=host are not optional. vLLM and the dataloaders use shared memory heavily; without them you get cryptic worker crashes.
• Out of VRAM? Add --gpu-memory-utilization 0.5 to any of the server commands (0.4 or lower on smaller cards) to shrink the KV cache.
• One vLLM at a time. vLLM pre-allocates VRAM, so don't run mineru-openai-server and a vlm-vllm-engine job on the same GPU concurrently.
• Backend cheat sheet: pipeline = fast, stable, no hallucination, CPU-capable · vlm-vllm-engine / vlm-transformers = highest accuracy · hybrid-* = high accuracy with native text extraction · *-http-client = thin client talking to a remote server.
• Fonts: Noto Core + Noto CJK and libgl1 are installed, so CJK documents and OpenCV-backed rendering work out of the box.
• Security: *-http-client backends and server_url are disabled when a server binds to 0.0.0.0. Pass --allow-public-http-client to re-enable them only if you accept the SSRF risk.

⁠Licenses

MinerU is released under the AGPL-3.0⁠ license; model weights carry their own terms. The image also contains the software distributed in vllm/vllm-openai. Review the licenses of everything bundled here before commercial use.