PaddlePaddle/PaddleOCR · error · ValueError

Invalid OCR version: {ocr_version}. Supported values are {_S

Error message

Invalid OCR version: {ocr_version}. Supported values are {_SUPPORTED_OCR_VERSIONS}.

What it means

PaddleOCR pipeline (paddleocr/_pipelines/ocr.py) validates the ocr_version keyword at construction time and raises ValueError when it is not None and not in _SUPPORTED_OCR_VERSIONS, which for this module is ['PP-OCRv3','PP-OCRv4','PP-OCRv5','PP-OCRv6']. The check runs before any model download, so it fails fast on a typo'd or outdated version string.

Source

Thrown at paddleocr/_pipelines/ocr.py:98

        text_recognition_batch_size=None,
        use_doc_orientation_classify=None,
        use_doc_unwarping=None,
        use_textline_orientation=None,
        text_det_limit_side_len=None,
        text_det_limit_type=None,
        text_det_thresh=None,
        text_det_box_thresh=None,
        text_det_unclip_ratio=None,
        text_det_input_shape=None,
        text_rec_score_thresh=None,
        return_word_box=None,
        text_rec_input_shape=None,
        lang=None,
        ocr_version=None,
        **kwargs,
    ):
        if ocr_version is not None and ocr_version not in _SUPPORTED_OCR_VERSIONS:
            raise ValueError(
                f"Invalid OCR version: {ocr_version}. Supported values are {_SUPPORTED_OCR_VERSIONS}."
            )

        if all(
            map(
                lambda p: p is None,
                (
                    text_detection_model_name,
                    text_detection_model_dir,
                    text_recognition_model_name,
                    text_recognition_model_dir,
                ),
            )
        ):
            det_model_name, rec_model_name = self._get_ocr_model_names(
                lang, ocr_version
            )
            if det_model_name is None or rec_model_name is None:

View on GitHub (pinned to 2661c7c0ef)

Solutions

Use an exact supported string, e.g. ocr_version='PP-OCRv5' (or omit it to get the default latest).
Check the case: the comparison is exact, 'pp-ocrv5' will not match 'PP-OCRv5'.
If you need a version like PP-OCRv2, pin an older paddleocr release that supports it.

Example fix

# before
ocr = PaddleOCR(ocr_version='PP-OCRv2')  # ValueError
# after
ocr = PaddleOCR(ocr_version='PP-OCRv5')

Defensive patterns

Strategy: validation

Validate before calling

from paddleocr._pipelines.ocr import _SUPPORTED_OCR_VERSIONS

def valid_ocr_version(v: str) -> bool:
    return v is None or v in _SUPPORTED_OCR_VERSIONS

Prevention

Source version strings from _SUPPORTED_OCR_VERSIONS rather than hardcoding
The check is case-sensitive: always use the canonical 'PP-OCRvN' casing
Note the ocr.py list differs from pp_structurev3.py — validate against the pipeline you use

When it happens

Trigger: Calling PaddleOCR(ocr_version='PP-OCR'), PaddleOCR(ocr_version='pp-ocrv5') (case-sensitive), PaddleOCR(ocr_version='PP-OCRv2'), or any string outside the supported list.

Common situations: Copy-pasting config from old PaddleOCR tutorials that use PP-OCRv2 or PP-OCR; assuming the flag is case-insensitive; mixing the ocr.py supported list (includes PP-OCRv6) with pp_structurev3's shorter list (only v3–v5).

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/2252b1edf51f120a. Report an issue: GitHub.