PaddlePaddle/PaddleOCR · error · ValueError

{model_name} is not supported. Please check if the model is

Error message

{model_name} is not supported. Please check if the model is supported by the PaddleOCR wheel.

What it means

TextRecognizer (tools/infer/predict_rec.py) reads inference.yml from the recognition model dir and rejects models whose Global.model_name is not in the whitelist (PP-OCRv5 mobile/server rec plus language-specific v5 rec models — korean, eslav, latin, en, th, el — and PP-OCRv6 tiny/small/medium). The same gate block also implements a convenience: for whitelisted models with a default dict path, the character dictionary embedded in inference.yml is written out to ppocr_keys.txt. The whitelist exists because the wheel's post-processing is tuned to these architectures/alphabets.

Source

Thrown at tools/infer/predict_rec.py:57

class TextRecognizer(object):
    def __init__(self, args, logger=None):
        if os.path.exists(f"{args.rec_model_dir}/inference.yml"):
            model_config = utility.load_config(f"{args.rec_model_dir}/inference.yml")
            model_name = model_config.get("Global", {}).get("model_name", "")
            if model_name and model_name not in [
                "PP-OCRv5_mobile_rec",
                "PP-OCRv5_server_rec",
                "korean_PP-OCRv5_mobile_rec",
                "eslav_PP-OCRv5_mobile_rec",
                "latin_PP-OCRv5_mobile_rec",
                "en_PP-OCRv5_mobile_rec",
                "th_PP-OCRv5_mobile_rec",
                "el_PP-OCRv5_mobile_rec",
                "PP-OCRv6_tiny_rec",
                "PP-OCRv6_small_rec",
                "PP-OCRv6_medium_rec",
            ]:
                raise ValueError(
                    f"{model_name} is not supported. Please check if the model is supported by the PaddleOCR wheel."
                )

            if args.rec_char_dict_path == "./ppocr/utils/ppocr_keys_v1.txt":
                rec_char_list = model_config.get("PostProcess", {}).get(
                    "character_dict", []
                )
                if rec_char_list:
                    new_rec_char_dict_path = f"{args.rec_model_dir}/ppocr_keys.txt"
                    with open(new_rec_char_dict_path, "w", encoding="utf-8") as f:
                        f.writelines([char + "\n" for char in rec_char_list])
                    args.rec_char_dict_path = new_rec_char_dict_path

        if logger is None:
            logger = get_logger()
        self.rec_image_shape = [int(v) for v in args.rec_image_shape.split(",")]
        self.rec_batch_num = args.rec_batch_num
        self.rec_algorithm = args.rec_algorithm

View on GitHub (pinned to 2661c7c0ef)

Solutions

  1. Switch to a whitelisted rec model (e.g. PP-OCRv5_mobile_rec or the matching language variant like korean_PP-OCRv5_mobile_rec)
  2. Download older zoo packages that ship without inference.yml, which bypass the gate
  3. If the architecture matches, edit Global.model_name in the model's inference.yml to a whitelisted name
  4. Use a source checkout of PaddleOCR (not the wheel) to run arbitrary rec models

Example fix

# before
--rec_model_dir=./inference/en_PP-OCRv4_mobile_rec  # ValueError

# after
--rec_model_dir=./inference/PP-OCRv5_mobile_rec
Defensive patterns

Strategy: validation

Validate before calling

import os, yaml
SUPPORTED_REC = {'PP-OCRv5_mobile_rec','PP-OCRv5_server_rec','korean_PP-OCRv5_mobile_rec','eslav_PP-OCRv5_mobile_rec','latin_PP-OCRv5_mobile_rec','en_PP-OCRv5_mobile_rec','th_PP-OCRv5_mobile_rec','el_PP-OCRv5_mobile_rec','PP-OCRv6_tiny_rec','PP-OCRv6_small_rec','PP-OCRv6_medium_rec'}
yml = os.path.join(rec_model_dir, 'inference.yml')
if os.path.exists(yml):
    name = yaml.safe_load(open(yml)).get('Global', {}).get('model_name', '')
    assert not name or name in SUPPORTED_REC, f'rec model {name!r} unsupported'

Try / catch

try:
    rec = TextRecognizer(args)
except ValueError as e:
    if 'not supported' in str(e):
        raise SystemExit('switch to a PP-OCRv5/v6 rec model or a legacy package without inference.yml')
    raise

Prevention

When it happens

Trigger: Setting --rec_model_dir to a PP-OCRv3/v4 rec model, a fine-tuned rec model, or a niche language rec model (e.g. cyrillic_PP-OCRv3) whose inference.yml carries a non-whitelisted model_name.

Common situations: Upgrading a project pinned to PP-OCRv3/v4 rec models; using models from the multi-language zoo that predate v5; fine-tuned exports keeping their original model_name; mixing wheel and source-checkout expectations.

Related errors

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