PaddlePaddle/PaddleOCR · critical · RuntimeError

A dependency error occurred during pipeline creation. Please

Error message

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

What it means

BasePipeline._create_paddlex_pipeline wraps paddlex's DependencyError in a RuntimeError when create_pipeline fails because required optional dependencies for the pipeline are not installed. The original cause is chained in the traceback. This is the pipeline-level twin of the predictor-level error in _models/base.py and always indicates an incomplete environment rather than bad arguments.

Source

Thrown at paddleocr/_pipelines/base.py:107

    def _get_merged_paddlex_config(self):
        if self._paddlex_config is None:
            config = load_pipeline_config(self._paddlex_pipeline_name)
        elif isinstance(self._paddlex_config, str):
            config = load_pipeline_config(self._paddlex_config)
        else:
            config = self._paddlex_config

        overrides = self._get_paddlex_config_overrides()

        return _merge_dicts(config, overrides)

    def _create_paddlex_pipeline(self):
        kwargs = prepare_common_init_args(None, self._common_args)
        try:
            return create_pipeline(config=self._merged_paddlex_config, **kwargs)
        except DependencyError as e:
            raise RuntimeError(
                "A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed."
            ) from e


class PipelineCLISubcommandExecutor(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)
        add_common_cli_opts(
            subparser,
            default_enable_hpi=_DEFAULT_ENABLE_HPI,
            allow_multiple_devices=True,
        )

View on GitHub (pinned to 2661c7c0ef)

Solutions

Read the chained original DependencyError in the traceback to find the exact missing distribution.
Install the missing packages: pip install paddlex and/or the extras the message names (e.g. paddlepaddle-gpu).
Use the dependency set from the official installation docs for your paddleocr version (e.g. pip install 'paddleocr[all]' or the documented serving extras).
Reproduce in a fresh venv to rule out conflicting site-packages.

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

def pipeline_deps_ok() -> bool:
    return all(importlib.util.find_spec(m) is not None for m in ('paddlex', 'paddle'))

Try / catch

try:
    pipe = PaddleOCR()
except RuntimeError as e:
    if 'dependency error' in str(e).lower() and e.__cause__ is not None:
        print('Missing dependency:', e.__cause__)
        print('Fix: pip install paddlex / the package named above')
        raise SystemExit(1)
    raise

Prevention

Use the documented dependency group for your pipeline (e.g. paddleocr[all])
Verify paddlex/paddlepaddle version compatibility matrix before upgrading either
Run a pipeline construction smoke test in CI for the exact image you deploy

When it happens

Trigger: Instantiating any paddleocr pipeline (PaddleOCR, PPStructureV3, PaddleOCRVL, PPChatOCRv3, ...) via constructor or CLI in an environment where paddlex or pipeline-specific extras (paddlepaddle, opencv, pdf rendering libs, etc.) are missing or version-mismatched.

Common situations: Fresh pip install of paddleocr without its dependency group; GPU paddlepaddle absent on a CUDA machine; paddlex upgraded independently of paddleocr and no longer matching; slim Docker images.

Related errors

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