openocr-mlt

Multilingual OCR with ScriptMoE ONNX Prefill/Decode recognition and PP-OCRv6 medium text detection. Run whole-page OCR, detection, or cropped text recognition locally.

Installation

Validated on Linux x86_64 with Python 3.10.12. Create one virtual environment for the installation you want to use.

CPU

python3.10 -m venv .venv-ocr-cpu
source .venv-ocr-cpu/bin/activate
python -m pip install openocr-mlt

NVIDIA CUDA

python3.10 -m venv .venv-ocr-cuda
source .venv-ocr-cuda/bin/activate
python -m pip install openocr-mlt-cuda

Both packages provide the same Python import and CLI. Install only one package per environment. The CUDA package requires a compatible NVIDIA driver and installs CUDA 12 and cuDNN 9 user-space libraries. ONNX inference runs without PyTorch.

Upgrading from 0.3.0

• A 0.3.0 CPU installation can be upgraded with python -m pip install --upgrade openocr-mlt.
• For a 0.3.0 CUDA installation, create a new environment and install openocr-mlt-cuda as shown above. The previous openocr-mlt[cuda] command applies to 0.3.0. A shared or explicitly configured model cache can be reused.

Python API

from openocr_mlt import OpenOCRMLT

with OpenOCRMLT(task="ocr") as ocr:
    page = ocr(image_path="page.jpg")
    print(page.text)

with OpenOCRMLT(task="det", device="cpu") as detector:
    boxes = detector(image_path="page.jpg")
    print([box.points for box in boxes])

with OpenOCRMLT(task="rec", device="cpu") as recognizer:
    lines = recognizer(image_path="crop.jpg")
    print([(line.text, line.score) for line in lines])

Pass an existing image path or use the image argument with a PIL image or a uint8 NumPy array. Arrays use BGR by default. Pass color_order="RGB" for RGB arrays. The default device is "auto". The CPU installation uses CPU. The CUDA installation uses CUDA when it can initialize the selected models and uses CPU when CUDA is unavailable. Use device="cpu" or device="cuda:0" to request a specific device. Explicit model directories and the original methods remain supported.

Model preparation

The first task call downloads the FP32 model bundle if it is absent from the cache. The bundle is hosted on ModelScope. Hugging Face and its mirror are fallback sources. The downloader verifies the archive and all 40 model files before installing the cache. The default cache is $XDG_CACHE_HOME/openocr-mlt or ~/.cache/openocr-mlt. The next task can reuse it offline.

Import a local archive in an offline environment with the following command.

python -m openocr_mlt fetch-models \
  --source ./scriptmoe-medium-fp32-20261101-v1.tar.gz --offline

Set offline=True on the Python task to require local assets. The fetch-models command prints the verified recognition and detector directories.

Command line

python -m openocr_mlt fetch-models --cache-dir ./models
python -m openocr_mlt ocr ./page.jpg \
  --model-dir ./models/scriptmoe-medium-fp32-20261101-v1/recognition \
  --det-model-dir ./models/scriptmoe-medium-fp32-20261101-v1/ppocrv6-medium-det-bce-v1 \
  --device cpu

The CLI also supports detect and recognize. Run python -m openocr_mlt --help for the available options.

Model Evaluation

The FP32 graphs were evaluated with openocr-mlt 0.3.0.dev14. The model bundle is unchanged.

Those model evaluations used Linux x86_64, Python 3.10.12, ONNX Runtime 1.20.0, an Intel Xeon Gold 6226R CPU, and an NVIDIA RTX 3090 GPU. One CPU/CUDA recognition whitespace difference was observed on TextMuSS. Additional platforms, hardware and quantized execution remain future work.

Sources

• ScriptMoE: multilingual recognition model and decoding design.
• ppocrv6_onnx: detection preprocessing and postprocessing reference.
• PP-OCRv6 medium: detector distributed through Paddle's official model storage.

Component attribution and licensing information are included in the package's THIRD_PARTY_NOTICES.txt and in the model repository's THIRD_PARTY_NOTICES.md.