PaddlePaddle/PaddleOCR · error · Exception

Install {module_name} failed, please install manually

Error message

Install {module_name} failed, please install manually

What it means

Exception from ppocr/utils/utility.py's auto-install helper: the requested module was missing, the helper attempted 'python -m pip install <install_name>' via subprocess, pip returned non-zero, and the CalledProcessError is re-raised as a plain Exception telling you to install manually. Common underlying pip failures: no network/proxy, incompatible version constraints, or no matching wheel for the Python version.

Source

Thrown at ppocr/utils/utility.py:195

    paddle.seed(seed)


def check_install(module_name, install_name):
    spec = importlib.util.find_spec(module_name)
    if spec is None:
        print(f"Warning! The {module_name} module is NOT installed")
        print(
            f"Try install {module_name} module automatically. You can also try to install manually by pip install {install_name}."
        )
        python = sys.executable
        try:
            subprocess.check_call(
                [python, "-m", "pip", "install", install_name],
                stdout=subprocess.DEVNULL,
            )
            print(f"The {module_name} module is now installed")
        except subprocess.CalledProcessError as exc:
            raise Exception(f"Install {module_name} failed, please install manually")
    else:
        print(f"{module_name} has been installed.")


class AverageMeter:
    def __init__(self):
        self.reset()

    def reset(self):
        """reset"""
        self.val = 0
        self.avg = 0
        self.sum = 0
        self.count = 0

    def update(self, val, n=1):
        """update"""
        self.val = val

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Install the package manually in the same environment as the printed install_name (the log line above the error shows the exact pip command to copy).
2. Fix pip connectivity first (proxy env vars, index URL) if the install failed for network reasons.
3. For no-wheel situations, pin a Python version supported by the package or install a prebuilt wheel file directly.

import importlib.util

def module_present(name) -> bool:
    return importlib.util.find_spec(name) is not None

if not module_present(module_name):
    raise SystemExit(f"{module_name} is required. Install it with: pip install {install_name}")

def is_module_installed(name) -> bool:
    import importlib.util
    return importlib.util.find_spec(name) is not None

try:
    auto_install_or_run(module_name, install_name)
except Exception:
    # explicit manual install with visible output instead of the silent auto-installer
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', install_name])
    auto_install_or_run(module_name, install_name)

When it happens

Trigger: Using a utility that lazily needs an optional module (the helper prints 'Warning! The X module is NOT installed' first) in an environment where pip cannot fetch or build the package.

Common situations: Offline or proxied environments where implicit pip installs fail; Python versions for which no wheel exists and source build fails; read-only site-packages without pip install --user fallback.

Related errors

• A dependency error occurred during predictor creation. Pleas
• A dependency error occurred during pipeline creation. Please
• Please install wandb using `pip install wandb`
• 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/78df5bffe510f8e0. Report an issue: GitHub.