PaddlePaddle/PaddleOCR · critical · RuntimeError

A dependency error occurred during predictor creation. Pleas

Error message

A dependency error occurred during predictor creation. Please refer to the installation documentation to ensure all required dependencies are installed.

What it means

BaseModel._create_paddlex_predictor wraps paddlex's DependencyError in a RuntimeError when create_predictor fails because optional runtime dependencies for the specific model are missing. The original DependencyError is chained (`from e`), so the full cause is visible in the traceback. It means the PaddleX/PaddleOCR installation is incomplete for that model, not that the code is wrong.

Source

Thrown at paddleocr/_models/base.py:80

    @classmethod
    @abc.abstractmethod
    def get_cli_subcommand_executor(cls):
        raise NotImplementedError

    def _get_extra_paddlex_predictor_init_args(self):
        return {}

    def _create_paddlex_predictor(self):
        kwargs = prepare_common_init_args(self._model_name, self._common_args)
        kwargs = {**self._get_extra_paddlex_predictor_init_args(), **kwargs}
        # Should we check model names?
        try:
            return create_predictor(
                model_name=self._model_name, model_dir=self._model_dir, **kwargs
            )
        except DependencyError as e:
            raise RuntimeError(
                "A dependency error occurred during predictor creation. Please refer to the installation documentation to ensure all required dependencies are installed."
            ) from e


class PredictorCLISubcommandExecutor(CLISubcommandExecutor):
    @property
    @abc.abstractmethod
    def subparser_name(self):
        raise NotImplementedError

    def add_subparser(self, subparsers):
        subparser = subparsers.add_parser(name=self.subparser_name)
        self._update_subparser(subparser)
        subparser.add_argument("--model_name", type=str, help="Name of the model.")
        subparser.add_argument(
            "--model_dir", type=str, help="Directory where the model is stored."
        )
        add_common_cli_opts(

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Inspect the chained original exception (`raise ... from e`) in the traceback to identify the exact missing package.
2. Reinstall/complete the dependency: pip install paddlex (or the version pinned by your paddleocr release), plus any model-specific extra it names.
3. Align versions: upgrade/downgrade paddlepaddle and paddlex to the combination documented for your paddleocr version.
4. Verify in a clean virtual environment per the official installation docs before rerunning.

import importlib.util

def paddlex_available() -> bool:
    return importlib.util.find_spec('paddlex') is not None

try:
    model = SomeModel()
except RuntimeError as e:
    if 'dependency error' in str(e).lower() and e.__cause__ is not None:
        missing = e.__cause__  # the original DependencyError names the package
        sys.exit(f"Install missing dependency then retry: {missing}")
    raise

When it happens

Trigger: Constructing any paddleocr model class (paddleocr._models.base.BaseModel subclasses, e.g. TextDetection, TextRecognition, VL recognition models) in a Python env where paddlex or its model-specific extras (paddlepaddle GPU build, opencv,rapid-json deps, encryption deps, etc.) are not installed.

Common situations: Installing paddleocr with a minimal pip install and then instantiating models; upgrading paddleocr to a version requiring a newer paddlex; CPU-only paddlepaddle while the model/predictor needs different extras; Docker images trimmed of optional wheels.

Related errors

• A dependency error occurred during pipeline creation. Please
• Please install wandb using `pip install wandb`
• Install {module_name} failed, please install manually
• worker mode requires Web Worker support in this environment.
• PaddleOCR.js requires an HTTP(S) origin so model assets can

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