{"id":7463,"library":"onnxocr-ppocrv5","title":"ONNX-based OCR (PP-OCRv5)","description":"`onnxocr-ppocrv5` is a Python library providing an ONNX-based inference pipeline for Baidu's PP-OCRv5. It aims for efficient optical character recognition by leveraging ONNX Runtime for high-performance inference. The current version is 0.0.14, and releases appear to be infrequent, typically focusing on specific model updates or bug fixes.","status":"active","version":"0.0.14","language":"en","source_language":"en","source_url":"https://github.com/ok-oldking/OnnxOCR","tags":["OCR","ONNX","PP-OCRv5","deep-learning","inference","computer-vision"],"install":[{"cmd":"pip install onnxocr-ppocrv5","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Fundamental library for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Required for image processing and manipulation within the OCR pipeline.","package":"opencv-python","optional":false},{"reason":"The core runtime for executing ONNX models. Installs the CPU version by default.","package":"onnxruntime","optional":false},{"reason":"Image processing library, often used for loading and saving various image formats.","package":"pillow","optional":false},{"reason":"Used to display progress bars, particularly during model downloads.","package":"tqdm","optional":false}],"imports":[{"symbol":"OnnxOCR","correct":"from onnxocr_ppocrv5 import OnnxOCR"}],"quickstart":{"code":"import os\nfrom onnxocr_ppocrv5 import OnnxOCR\n\n# NOTE: Replace with a path to your actual image file\n# For demonstration, we assume an image 'example.png' exists in the current directory\n# In a real application, you might download or provide an actual image path.\nimage_path = os.environ.get('OCR_IMAGE_PATH', 'example.png')\n\n# The first initialization will automatically download necessary models (~300-500 MB)\n# This requires an internet connection and can take some time.\nprint(\"Initializing OnnxOCR model... (models will download on first run)\")\nocr = OnnxOCR()\nprint(\"OCR model initialized.\")\n\n# Perform OCR on an image file path\n# Ensure the image_path points to a valid image accessible by the script.\nif os.path.exists(image_path):\n    try:\n        result = ocr(image_path)\n        print(\"OCR Result:\")\n        for box_info in result:\n            # Each box_info is a dictionary with 'box' and 'text'\n            print(f\"  Text: {box_info['text']}, Box: {box_info['box']}\")\n    except Exception as e:\n        print(f\"Error performing OCR: {e}\")\n        print(\"Please ensure the image_path is valid and the image is not corrupt.\")\nelse:\n    print(f\"Error: Image file not found at '{image_path}'. Please provide a valid image path.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `OnnxOCR` model and perform OCR on a local image file. The model automatically downloads necessary ONNX files on the first run, which requires an internet connection and sufficient disk space."},"warnings":[{"fix":"Ensure an active internet connection and sufficient disk space for model storage (~500 MB). The models are cached locally for subsequent runs.","message":"Model files are automatically downloaded during the first initialization of the `OnnxOCR` object. This process requires an active internet connection and can download significant data (hundreds of MBs), potentially causing delays on the first run.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To enable GPU inference: `pip uninstall onnxruntime` then `pip install onnxruntime-gpu` (ensure you have compatible CUDA drivers and toolkit installed).","message":"By default, `onnxocr-ppocrv5` installs `onnxruntime` (the CPU version). For GPU acceleration, you must manually uninstall `onnxruntime` and install `onnxruntime-gpu`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pin the exact version in your `requirements.txt` (`onnxocr-ppocrv5==0.0.14`) for production environments. Regularly check the GitHub repository for updates and release notes.","message":"The library is in early development (0.0.x versions). While core functionality is generally stable, the API might undergo minor changes or refinements in future patch releases without explicit breaking change notifications.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Always verify that the image path exists and points to a valid, supported image file (e.g., JPG, PNG, BMP). Use `os.path.exists()` for paths.","message":"Incorrect image paths or unsupported image formats (e.g., corrupted files, uncommon extensions) passed to the `ocr()` method will result in errors, typically `FileNotFoundError` or internal `OpenCV` errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install onnxocr-ppocrv5`.","cause":"The `onnxocr-ppocrv5` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'onnxocr_ppocrv5'"},{"fix":"Ensure you have an internet connection during the first run. Check disk space. If the issue persists, try deleting the cached model directory (often in `~/.cache/onnxocr_ppocrv5` or similar) to force a re-download. Check for proxy or firewall issues.","cause":"This usually indicates an issue with the downloaded ONNX model files, such as corruption during download, insufficient disk space, or incorrect permissions.","error":"onnxruntime.capi.onnxruntime_pybind11_state.RuntimeException: [ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Failed to load model from ..."},{"fix":"Double-check the image file path for typos and ensure the file actually exists at that location relative to where your script is running. Use absolute paths or `os.path.join` for robustness.","cause":"The image file specified in the `ocr()` call does not exist at the provided path, or the path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/image.jpg'"}]}