Skip to content

πŸ“„ Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.

feat(docker): add per-engine Docker dev environments (#649)

locviettri1f78b76eb470
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..77be62f
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,37 @@
+# RapidOCR Docker Dev Environments
+COMPOSE_FILE := docker/docker-compose.yaml
+ENGINES := onnxruntime-cpu onnxruntime-gpu tensorrt paddle openvino pytorch mnn
+
+.PHONY: help build-all clean $(foreach e,$(ENGINES),build-$(e) test-$(e) shell-$(e))
+
+help:
+ @echo "RapidOCR Docker Dev Environments"
+ @echo ""
+ @echo "Usage:"
+ @echo " make build-{engine} Build a dev image"
+ @echo " make test-{engine} Run tests in container"
+ @echo " make shell-{engine} Open bash shell in container"
+ @echo " make build-all Build all images"
+ @echo " make clean Remove all containers and images"
+ @echo ""
+ @echo "Engines: $(ENGINES)"
+ @echo ""
+ @echo "Examples:"
+ @echo " make build-tensorrt"
+ @echo " make test-onnxruntime-cpu"
+ @echo " make shell-pytorch"
+
+build-%:
+ docker compose -f $(COMPOSE_FILE) build $*
+
+test-%:
+ docker compose -f $(COMPOSE_FILE) run --rm $* pytest tests/ -v
+
+shell-%:
+ docker compose -f $(COMPOSE_FILE) run --rm $* bash
+
+build-all:
+ docker compose -f $(COMPOSE_FILE) build
+
+clean:
+ docker compose -f $(COMPOSE_FILE) down --rmi local --volumes
diff --git a/README.md b/README.md
index 8895269..5809836 100755
--- a/README.md
+++ b/README.md
@@ -71,6 +71,22 @@ print(result)
result.vis("vis_result.jpg")
```
+### 🐳 Docker
+
+Docker development environments are available for all supported inference engines:
+
+```bash
+# Build and test with ONNX Runtime (CPU)
+make build-onnxruntime-cpu
+make test-onnxruntime-cpu
+
+# Or use any engine: onnxruntime-gpu, tensorrt, paddle, openvino, pytorch, mnn
+make build-tensorrt
+make shell-tensorrt
+```
+
+See [docker/README.md](./docker/README.md) for full setup instructions, GPU configuration, and troubleshooting.
+
### πŸ“š Documentation
Full documentation can be found on [docs](https://rapidai.github.io/RapidOCRDocs/), in Chinese.
diff --git a/docker/.dockerignore b/docker/.dockerignore
new file mode 100644
index 0000000..8b3de09
--- /dev/null
+++ b/docker/.dockerignore
@@ -0,0 +1,20 @@
+.git
+__pycache__
+*.pyc
+*.pyo
+*.egg-info
+dist/
+build/
+.tox/
+.pytest_cache/
+.mypy_cache/
+python/rapidocr/models/
+python/benchmark_*
+python/pred.txt
+python/merged_benchmark_report_*
+python/tensorrt_build_logs_*
+python/validate_benchmark_*
+python/generate_merged_report.py
+python/mnn_benchmark_reference.md
+*.engine
+.mcp.json
diff --git a/docker/Dockerfile.base b/docker/Dockerfile.base
new file mode 100644
index 0000000..f4b658c
--- /dev/null
+++ b/docker/Dockerfile.base
@@ -0,0 +1,35 @@
+FROM python:3.10-slim-bookworm
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+WORKDIR /app
+
+# System dependencies for opencv, pyclipper, shapely C extensions
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ libgl1 \
+ libglib2.0-0 \
+ libsm6 \
+ libxext6 \
+ libxrender1 \
+ gcc \
+ g++ \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy only requirements first for layer caching
+COPY python/requirements.txt /tmp/requirements.txt
+
+# Install core deps with opencv-headless (no GUI needed in container)
+RUN pip install --no-cache-dir --upgrade pip && \
+ pip install --no-cache-dir -r /tmp/requirements.txt && \
+ pip uninstall -y opencv-python 2>/dev/null; \
+ pip install --no-cache-dir opencv-python-headless && \
+ pip install --no-cache-dir pytest && \
+ rm /tmp/requirements.txt
+
+# Copy source (bind-mounted at runtime for live editing via docker-compose)
+COPY python/ /app/
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.mnn b/docker/Dockerfile.mnn
new file mode 100644
index 0000000..68ce284
--- /dev/null
+++ b/docker/Dockerfile.mnn
@@ -0,0 +1,5 @@
+FROM rapidocr-base:latest
+
+RUN pip install --no-cache-dir MNN
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.onnxruntime-cpu b/docker/Dockerfile.onnxruntime-cpu
new file mode 100644
index 0000000..30b1179
--- /dev/null
+++ b/docker/Dockerfile.onnxruntime-cpu
@@ -0,0 +1,5 @@
+FROM rapidocr-base:latest
+
+RUN pip install --no-cache-dir onnxruntime
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.onnxruntime-gpu b/docker/Dockerfile.onnxruntime-gpu
new file mode 100644
index 0000000..5a0c645
--- /dev/null
+++ b/docker/Dockerfile.onnxruntime-gpu
@@ -0,0 +1,49 @@
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+WORKDIR /app
+
+# Install Python 3.10 and system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ software-properties-common \
+ && add-apt-repository ppa:deadsnakes/ppa \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends \
+ python3.10 \
+ python3.10-venv \
+ python3.10-dev \
+ python3-pip \
+ libgl1 \
+ libglib2.0-0 \
+ libsm6 \
+ libxext6 \
+ libxrender1 \
+ gcc \
+ g++ \
+ && rm -rf /var/lib/apt/lists/*
+
+# Make python3.10 the default
+RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 && \
+ update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1
+
+# Copy and install deps
+COPY python/requirements.txt /tmp/requirements.txt
+
+RUN python -m pip install --no-cache-dir --upgrade pip && \
+ pip install --no-cache-dir -r /tmp/requirements.txt && \
+ pip uninstall -y opencv-python 2>/dev/null; \
+ pip install --no-cache-dir opencv-python-headless && \
+ pip install --no-cache-dir pytest && \
+ rm /tmp/requirements.txt
+
+# Install ONNX Runtime GPU
+RUN pip install --no-cache-dir onnxruntime-gpu
+
+# Copy source (bind-mounted at runtime for live editing via docker-compose)
+COPY python/ /app/
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.openvino b/docker/Dockerfile.openvino
new file mode 100644
index 0000000..02af7bb
--- /dev/null
+++ b/docker/Dockerfile.openvino
@@ -0,0 +1,5 @@
+FROM rapidocr-base:latest
+
+RUN pip install --no-cache-dir openvino==2023.3.0
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.paddle b/docker/Dockerfile.paddle
new file mode 100644
index 0000000..b54bf84
--- /dev/null
+++ b/docker/Dockerfile.paddle
@@ -0,0 +1,7 @@
+FROM rapidocr-base:latest
+
+# PaddlePaddle CPU uses a special index URL
+RUN pip install --no-cache-dir paddlepaddle==3.1.1 \
+ -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.pytorch b/docker/Dockerfile.pytorch
new file mode 100644
index 0000000..927cb49
--- /dev/null
+++ b/docker/Dockerfile.pytorch
@@ -0,0 +1,7 @@
+FROM rapidocr-base:latest
+
+# PyTorch CPU from official index
+RUN pip install --no-cache-dir torch torchvision torchaudio \
+ --index-url https://download.pytorch.org/whl/cpu
+
+CMD ["bash"]
diff --git a/docker/Dockerfile.tensorrt b/docker/Dockerfile.tensorrt
new file mode 100644
index 0000000..eb1c83a
--- /dev/null
+++ b/docker/Dockerfile.tensorrt
@@ -0,0 +1,39 @@
+FROM nvcr.io/nvidia/deepstream:7.0-gc-triton-devel
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+WORKDIR /app
+
+# System deps for opencv and build tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ libgl1 \
+ libglib2.0-0 \
+ libsm6 \
+ libxext6 \
+ libxrender1 \
+ gcc \
+ g++ \
+ python3-pip \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy and install deps
+COPY python/requirements.txt /tmp/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade pip && \
+ pip install --no-cache-dir -r /tmp/requirements.txt && \
+ pip uninstall -y opencv-python 2>/dev/null; \
+ pip install --no-cache-dir opencv-python-headless && \
+ pip install --no-cache-dir pytest && \
+ rm /tmp/requirements.txt
+
+# TensorRT Python bindings must match the system TRT version (8.6.1 in DeepStream 7.0).
+# cuda-python must match the container's CUDA 12.x toolkit.
+RUN pip install --no-cache-dir "tensorrt>=8.6,<8.7" "cuda-python>=12.0,<13.0"
+
+# Copy source (bind-mounted at runtime for live editing via docker-compose)
+COPY python/ /app/
+
+CMD ["bash"]
diff --git a/docker/README.md b/docker/README.md
index b208dcc..ac7585c 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -1,25 +1,185 @@
-# RapidOCR API Docker
+# Docker Development Environments
-## Quickstart
+Pre-configured Docker images for developing and testing RapidOCR with each supported inference engine.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) (20.10+)
+- [Docker Compose](https://docs.docker.com/compose/install/) (v2)
+- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) (GPU images only)
+
+## Available Images
+
+| Image | Engine | Base Image | GPU Required |
+|-------|--------|------------|:------------:|
+| `onnxruntime-cpu` | ONNX Runtime (CPU) | `python:3.10-slim-bookworm` | No |
+| `onnxruntime-gpu` | ONNX Runtime (CUDA) | `nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04` | Yes |
+| `tensorrt` | NVIDIA TensorRT | `nvcr.io/nvidia/deepstream:7.0-gc-triton-devel` | Yes |
+| `paddle` | PaddlePaddle (CPU) | `python:3.10-slim-bookworm` | No |
+| `openvino` | Intel OpenVINO | `python:3.10-slim-bookworm` | No |
+| `pytorch` | PyTorch (CPU) | `python:3.10-slim-bookworm` | No |
+| `mnn` | MNN | `python:3.10-slim-bookworm` | No |
+
+## Quick Start
+
+All commands run from the **repository root**.
+
+### Build an image
```bash
-docker pull qingchen0607/rapid-ocr-api:v20250619
-docker run -itd --restart=always --name rapidocr_api -p 9005:9005 qingchen0607/rapid-ocr-api:v20250619
+make build-onnxruntime-cpu
+```
+
+### Run tests
-# http://<ip>:9005/docs
+```bash
+make test-onnxruntime-cpu
```
-## Local Build
+### Open an interactive shell
-```shell
-cd docker
+```bash
+make shell-onnxruntime-cpu
+```
-#chmod +x docker_build&run.sh docker_stop&clean.sh
+### Build all images
-# build image and run
-./docker_build&run.sh
+```bash
+make build-all
+```
-# stop and rm image
-./docker_stop&clean.sh
+### Clean up
+
+```bash
+make clean
```
+## Using docker compose directly
+
+```bash
+# Build
+docker compose -f docker/docker-compose.yaml build onnxruntime-cpu
+
+# Run tests
+docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu pytest tests/ -v
+
+# Run a single test
+docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu pytest tests/test_engine.py -k "onnxruntime" -v
+
+# Interactive shell
+docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu bash
+```
+
+## GPU Images
+
+GPU images (`onnxruntime-gpu`, `tensorrt`) require the NVIDIA Container Toolkit and a compatible NVIDIA GPU.
+
+Verify your GPU is accessible:
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
+```
+
+Then build and use GPU images normally:
+
+```bash
+make build-tensorrt
+make test-tensorrt
+make shell-tensorrt
+```
+
+> **Note:** TensorRT builds optimized engine files from ONNX models on first run. This takes several minutes per model. Subsequent runs use cached engines from the persistent model volume.
+
+## How It Works
+
+### Source Code Mounting
+
+Your local `python/` directory is bind-mounted into the container at `/app`. Any code changes you make on the host are immediately reflected inside the container β€” no rebuild needed.
+
+### Model Caching
+
+A shared Docker volume (`rapidocr-models`) is mounted at `/app/rapidocr/models/`. Models are automatically downloaded on first use and cached in this volume. The cache persists across container rebuilds, so models are only downloaded once.
+
+To clear the model cache:
+
+```bash
+docker volume rm rapidocr-models
+```
+
+### Architecture
+
+```
+docker/
+β”œβ”€β”€ Dockerfile.base # Shared base: Python 3.10, system deps, core pip packages
+β”œβ”€β”€ Dockerfile.onnxruntime-cpu # extends base + onnxruntime
+β”œβ”€β”€ Dockerfile.onnxruntime-gpu # standalone CUDA image + onnxruntime-gpu
+β”œβ”€β”€ Dockerfile.tensorrt # standalone DeepStream image + tensorrt + cuda-python
+β”œβ”€β”€ Dockerfile.paddle # extends base + paddlepaddle
+β”œβ”€β”€ Dockerfile.openvino # extends base + openvino
+β”œβ”€β”€ Dockerfile.pytorch # extends base + torch
+β”œβ”€β”€ Dockerfile.mnn # extends base + MNN
+β”œβ”€β”€ docker-compose.yaml # Service definitions, volumes, GPU reservations
+└── .dockerignore # Excludes .git, models, build artifacts
+Makefile # Convenience targets (repo root)
+```
+
+CPU images extend `Dockerfile.base`. GPU images (`onnxruntime-gpu`, `tensorrt`) use NVIDIA base images and replicate the base setup because they need CUDA pre-installed.
+
+## Examples
+
+### Run OCR from the command line
+
+```bash
+make shell-onnxruntime-cpu
+# Inside container:
+python -c "
+from rapidocr import RapidOCR
+engine = RapidOCR()
+result = engine('tests/test_files/ch_en_num.jpg')
+print(result)
+"
+```
+
+### Run with a specific engine
+
+```bash
+make shell-pytorch
+# Inside container:
+python -c "
+from rapidocr import RapidOCR, EngineType
+engine = RapidOCR(params={
+ 'Det.engine_type': EngineType.TORCH,
+ 'Cls.engine_type': EngineType.TORCH,
+ 'Rec.engine_type': EngineType.TORCH,
+})
+result = engine('tests/test_files/ch_en_num.jpg')
+print(result)
+"
+```
+
+### Run a specific test file
+
+```bash
+docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu \
+ pytest tests/test_engine.py::test_ppocrv5_rec_mobile -v
+```
+
+## Troubleshooting
+
+### `docker compose` command not found
+
+Ensure you have Docker Compose v2 installed. On older systems, the command may be `docker-compose` (with hyphen) instead of `docker compose` (with space).
+
+### GPU not detected inside container
+
+1. Verify the NVIDIA driver: `nvidia-smi`
+2. Verify the container toolkit: `docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi`
+3. If using Docker Desktop, enable GPU support in Settings > Resources > GPU.
+
+### TensorRT `CUDA initialization failure with error: 35`
+
+This means the TensorRT or CUDA Python version doesn't match your host driver. The Dockerfile pins `tensorrt>=8.6,<8.7` and `cuda-python>=12.0,<13.0` for DeepStream 7.0. If your driver is older, you may need to adjust these versions.
+
+### Models re-download every time
+
+Ensure the `rapidocr-models` volume is mounted. Check with `docker volume ls | grep rapidocr`.
diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml
new file mode 100644
index 0000000..06d2358
--- /dev/null
+++ b/docker/docker-compose.yaml
@@ -0,0 +1,102 @@
+services:
+ onnxruntime-cpu:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.onnxruntime-cpu
+ image: rapidocr-onnxruntime-cpu:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ stdin_open: true
+ tty: true
+
+ onnxruntime-gpu:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.onnxruntime-gpu
+ image: rapidocr-onnxruntime-gpu:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: 1
+ capabilities: [gpu]
+ stdin_open: true
+ tty: true
+
+ tensorrt:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.tensorrt
+ image: rapidocr-tensorrt:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: 1
+ capabilities: [gpu]
+ stdin_open: true
+ tty: true
+
+ paddle:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.paddle
+ image: rapidocr-paddle:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ stdin_open: true
+ tty: true
+
+ openvino:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.openvino
+ image: rapidocr-openvino:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ stdin_open: true
+ tty: true
+
+ pytorch:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.pytorch
+ image: rapidocr-pytorch:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ stdin_open: true
+ tty: true
+
+ mnn:
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile.mnn
+ image: rapidocr-mnn:latest
+ working_dir: /app
+ volumes:
+ - models:/app/rapidocr/models
+ - ../python:/app
+ stdin_open: true
+ tty: true
+
+volumes:
+ models:
+ name: rapidocr-models
diff --git a/docker/docker_build&run.sh b/docker/docker_build&run.sh
deleted file mode 100644
index 12ce46a..0000000
--- a/docker/docker_build&run.sh
+++ /dev/null
@@ -1,2 +0,0 @@
-docker build -t rapidocr_api --network host .
-docker run -itd --restart=always --name rapidocr_api -p 9005:9005 rapidocr_api
\ No newline at end of file
diff --git a/docker/docker_stop&clean.sh b/docker/docker_stop&clean.sh
deleted file mode 100644
index c50e4e7..0000000
--- a/docker/docker_stop&clean.sh
+++ /dev/null
@@ -1,3 +0,0 @@
-docker stop rapidocr_api
-docker rm rapidocr_api
-docker rmi rapidocr_api
\ No newline at end of file
diff --git a/docker/dockerfile b/docker/dockerfile
deleted file mode 100644
index df4f670..0000000
--- a/docker/dockerfile
+++ /dev/null
@@ -1,8 +0,0 @@
-FROM python:3.10.11-slim-buster
-ENV DEBIAN_FRONTEND=noninteractive
-WORKDIR /app
-RUN pip install --no-cache-dir onnxruntime rapidocr_api -i https://mirrors.aliyun.com/pypi/simple
-RUN pip uninstall -y opencv-python && \
- pip install --no-cache-dir opencv-python-headless -i https://mirrors.aliyun.com/pypi/simple
-EXPOSE 9005
-CMD ["bash", "-c", "rapidocr_api -ip 0.0.0.0 -p 9005 -workers 2"]
\ No newline at end of file