Skip to main content

OnnxOCR PP-OCRv5

ONNX-based PP-OCRv5 text detection and recognition with selectable ONNX Runtime and OpenVINO inference backends. This project is a fork of jingsongliujing/OnnxOCR and is published on PyPI as onnxocr-ppocrv5.

The package includes the PP-OCRv5 detection, angle-classification, recognition, and character-dictionary assets. It performs inference only; training and model conversion are outside the scope of this package.

For Chinese documentation, see Readme_cn.md.

Features

  • Two inference backends: run the same PP-OCRv5 pipeline with either ONNX Runtime or OpenVINO.
  • Intel NPU acceleration: OpenVINO can use a compatible Intel NPU and falls back to OpenVINO CPU when the NPU or its driver is unavailable.
  • CPU inference: ONNX Runtime CPU and OpenVINO CPU are both supported without requiring specialized accelerator hardware.
  • Complete OCR pipeline: bundled models provide text detection, optional angle classification, and text recognition.
  • Purpose-specific installations: separate onnx, openvino, dev, and build profiles let users install only the backend or tooling they need.
  • Optimized model caching: optimized ONNX Runtime models and OpenVINO cache data are reused across runs to reduce repeated initialization work.
  • Annotated output: detected boxes and recognized text can be rendered to an output image with the included sav2Img helper.

Requirements

  • Python 3.8 or newer
  • One inference backend: ONNX Runtime or OpenVINO
  • An image represented as a NumPy array, normally loaded with OpenCV
  • OpenVINO NPU execution additionally requires compatible Intel NPU hardware and drivers

pyclipper, shapely, and Pillow are installed automatically. NumPy and OpenCV are intentionally not declared as mandatory package dependencies. This avoids forcing a particular NumPy version or OpenCV distribution on applications that already manage those packages. Install compatible NumPy and OpenCV packages for your environment before using OCR.

The inference engines are separate optional dependency profiles so an installation does not need to carry both large runtimes.

Dependency profiles

The package defines independent optional dependency profiles in pyproject.toml:

Profile Installed packages Intended use
Base pyclipper, shapely, Pillow OCR preprocessing and post-processing
onnx onnxruntime ONNX Runtime inference
openvino openvino OpenVINO CPU or Intel NPU inference
dev NumPy, OpenCV headless, onnxruntime, openvino, pytest Complete development and test environment for both backends
build build, twine Building and validating release artifacts

The dev profile already includes both inference backends and all Python packages required by the test suite. Add build when the same environment also needs to create release artifacts:

python -m pip install -e ".[dev,build]"

NumPy and OpenCV remain application-managed for normal package installations. They are included unpinned in dev only, with headless OpenCV selected for consistent local and CI test environments.

Installation

Upgrade pip first so it can resolve wheels for the selected Python version:

python -m pip install --upgrade pip

Install NumPy and one OpenCV distribution if the application does not already provide them. Headless OpenCV is appropriate for servers and containers:

python -m pip install numpy opencv-python-headless

Desktop applications may use opencv-python, while applications that need the additional OpenCV modules may use opencv-contrib-python. Avoid installing multiple OpenCV distributions in the same environment because they all provide the cv2 module.

ONNX Runtime

Install the onnx profile for CPU inference with ONNX Runtime:

python -m pip install "onnxocr-ppocrv5[onnx]"

Use use_openvino=False when constructing the OCR pipeline. This is also the current default, but setting it explicitly makes the chosen backend clear:

import cv2

from onnxocr.onnx_paddleocr import ONNXPaddleOcr

image = cv2.imread("image.jpg")
if image is None:
    raise FileNotFoundError("image.jpg")

ocr = ONNXPaddleOcr(
    use_openvino=False,
    use_angle_cls=False,
)
result = ocr.ocr(image)
print(result)

OpenVINO CPU

Install the openvino profile:

python -m pip install "onnxocr-ppocrv5[openvino]"

Select OpenVINO and disable the NPU probe to run on CPU only:

import cv2

from onnxocr.onnx_paddleocr import ONNXPaddleOcr

image = cv2.imread("image.jpg")
if image is None:
    raise FileNotFoundError("image.jpg")

ocr = ONNXPaddleOcr(
    use_openvino=True,
    use_npu=False,
    use_angle_cls=False,
)
result = ocr.ocr(image)
print(result)

OpenVINO NPU

The same openvino profile supports Intel NPU execution. Enable the NPU probe with use_npu=True:

ocr = ONNXPaddleOcr(
    use_openvino=True,
    use_npu=True,
    use_angle_cls=True,
)

The pipeline validates the NPU driver, initializes the NPU models, and runs an OCR smoke test against an OpenCV-generated okscript image. If NPU setup or the first inference fails, it reinitializes the complete pipeline with use_npu=False. The initialization completion log records the smoke-test or fallback result. Enabling angle classification loads the bundled classification model in addition to detection and recognition.

Install both backends

Install both profiles when comparing backends or running the full CPU integration suite:

python -m pip install "onnxocr-ppocrv5[onnx,openvino]"

Installing onnxocr-ppocrv5 without an extra installs the declared post-processing dependencies, but it cannot perform model inference until an inference backend, NumPy, and an OpenCV distribution are available.

Result format and saving an annotated image

ocr.ocr(image) returns one result list for the input image. Each detected line contains its four-point polygon followed by (text, confidence):

[
    [
        [box_points, (recognized_text, confidence)],
        ...
    ]
]

Use sav2Img to write a copy with boxes and recognized text:

from onnxocr.onnx_paddleocr import sav2Img

sav2Img(image, result, "ocr-result.jpg")

Development

Clone the repository, create a virtual environment, and install the project in editable mode with the development tools and the backend you need.

PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Linux or macOS:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

This installs both supported inference backends and everything needed to run the test suite. The equivalent requirements-file command is:

python -m pip install -r requirements-dev.txt

Add the independent build profile only when packaging distributions:

python -m pip install -e ".[dev,build]"

Testing

The default command runs only the fast unit tests. Integration tests are excluded by the configuration in pyproject.toml:

pytest

Run the CPU integration tests with the development profile:

python -m pip install -e ".[dev]"
pytest -m "integration and not npu"

Run the hardware-specific OpenVINO NPU tests only on a configured NPU machine:

python -m pip install -e ".[dev]"
pytest -m "integration and npu"

A skipped integration test normally means its backend is not installed. An NPU test can also fail or fall back to CPU when the required hardware or driver is unavailable.

Building distributions

The build profile is independent of the inference backends because building a distribution does not run model inference. Install it, build both distribution formats, and validate their metadata:

python -m pip install -e ".[build]"
python -m build
python -m twine check dist/*

For development, tests, and packaging in one environment, combine the profiles:

python -m pip install -e ".[dev,build]"

The onnx and openvino extras are recorded in wheel metadata; neither backend is bundled inside the wheel.

Metadata

Release files for onnxocr-ppocrv5 0.0.23

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onnxocr-ppocrv5 0.0.23
File Size Uploaded Provenance Actions
onnxocr_ppocrv5-0.0.23.tar.gz 19.2 MB With provenance Details for onnxocr_ppocrv5-0.0.23.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onnxocr-ppocrv5 0.0.23
File Interpreter ABI Platform Actions
onnxocr_ppocrv5-0.0.23-py3-none-any.whl Python 3 none any Details for onnxocr_ppocrv5-0.0.23-py3-none-any.whl

Total release size: 38.3 MB

Release files / onnxocr_ppocrv5-0.0.23.tar.gz

Download URL onnxocr_ppocrv5-0.0.23.tar.gz
Size 19.2 MB
Tags Source
SHA-256 checksum
How to use checksums
e7d4d4f521bd29a8c5849121e0111ed9d307e68737a79786a2abb38781bc1559
BLAKE2b-256 checksum
How to use checksums
e62815c72d90384e06b0596a0ca1f60964c21e0049c249e9bd51cc692a4f818d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / onnxocr_ppocrv5-0.0.23-py3-none-any.whl

Download URL onnxocr_ppocrv5-0.0.23-py3-none-any.whl
Size 19.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
63476d092e2194756775ac57af0500389054b5ba0fe9f777f882ccd33067263f
BLAKE2b-256 checksum
How to use checksums
8b699e21a9884769a604ca43928da8eb6c4917188bde21d4d649b2a436849f4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for onnxocr-ppocrv5 0.0.23

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for onnxocr_ppocrv5-0.0.23.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page