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

Tested on Linux x86_64 with Python 3.10. Create a virtual environment and install the package.

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

On Linux x86_64 this installation includes the CPU and CUDA providers in one ONNX Runtime package. NVIDIA CUDA requires a compatible driver. On the first CUDA inference, the Python task API reuses compatible system libraries or prepares the pinned CUDA 12 and cuDNN 9 libraries in the user's cache. CPU inference does not need these libraries. The first GPU setup can download about 1.32 GB of runtime libraries, separate from the model bundle. Download progress and source retries are written to standard error. If preparation fails, correct the reported issue and create a new OCR instance to retry, or set device="cpu". PyTorch is optional.

For an existing 0.4.0 CPU or CUDA installation, use a new environment for this version and reuse the model cache. Only one ONNX Runtime distribution and one OCR package may be installed in each environment.

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 runtime 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 use local models and CUDA libraries only. 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. For CLI CUDA use, prepare the CUDA cache with a Python task first or provide compatible local libraries. 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.