Docker Development Environments

Pre-configured Docker images for developing and testing RapidOCR with each supported inference engine.

Prerequisites

• Docker (20.10+)
• Docker Compose (v2)
• NVIDIA Container Toolkit (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

make build-onnxruntime-cpu

Run tests

make test-onnxruntime-cpu

Open an interactive shell

make shell-onnxruntime-cpu

Build all images

make build-all

Clean up

make clean

Using docker compose directly

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

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Then build and use GPU images normally:

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:

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

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

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

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.