Troubleshooting PaddleOCR Installation Errors: A Complete Guide to Common Setup Issues

Troubleshooting PaddleOCR installation errors requires verifying PaddlePaddle wheel compatibility with your hardware, installing correct optional dependency groups for advanced features, and using specific CUDA/TensorRT versions for GPU acceleration.

PaddleOCR is a modular OCR toolkit built on the PaddlePaddle deep-learning framework within the PaddlePaddle/PaddleOCR repository. While the toolkit supports flexible deployment via pip, Docker, and specialized Windows wheels, troubleshooting PaddleOCR installation errors typically involves resolving mismatches between the framework layer and your hardware configuration. Understanding the three-tier architecture—core framework, default OCR pipelines, and optional document-understanding modules—provides the context needed to diagnose import failures and runtime crashes.

Understanding the PaddleOCR Architecture

PaddleOCR organizes its codebase into three logical layers that dictate installation requirements and dependency groups.

Framework Layer

The Framework layer provides the core deep-learning runtime through PaddlePaddle. According to docs/version3.x/installation.md, this layer requires specific wheel versions (paddlepaddle==3.2.0 for CPU or paddlepaddle-gpu==3.2.0 for GPU) that must exactly match your operating system and NVIDIA driver version to avoid compilation mismatches.

Core OCR Pipelines

The Core OCR pipelines handle text detection, recognition, and classification through scripts like tools/infer_det.py, tools/infer_rec.py, and tools/infer_cls.py. These components function with the base installation and require no extra dependencies beyond the core framework and requirements.txt.

Optional Document-Understanding Pipelines

The Optional layer includes specialized functionality for table extraction, formula recognition, and layout analysis housed in ppstructure/, ppstructure/table/, and ppstructure/layout/. These features require additional dependency groups defined in setup.cfg or pyproject.toml (located in mcp_server/), such as [doc-parser], [ie], or [trans], which are not included in the base paddleocr package.

Common Installation Error Categories

Installation failures usually map to specific mismatches between these architectural layers and your environment.

PaddlePaddle Version Mismatch

Symptoms: ImportError: No module named 'paddle' or RuntimeError: Paddle compiled with different CUDA version.

Root cause: The installed PaddlePaddle wheel does not match your OS or GPU driver version. GPU wheels require specific NVIDIA driver versions: ≥450.80.02 for CUDA 11.8 or ≥550.54.14 for CUDA 12.6.

Fix: Install the exact wheel specified in docs/version3.x/installation.md. Verify your driver compatibility before selecting the CPU, GPU, or Windows-50-Series wheel.

import paddle
print(f"PaddlePaddle version: {paddle.__version__}")
print(f"Detected device: {paddle.get_device()}")

Missing Optional Dependencies

Symptoms: ModuleNotFoundError: No module named 'ppstructure' or ImportError: cannot import name 'TableRecognizer' when running document analysis code.

Root cause: The base paddleocr package excludes optional pipelines. The dynamic pipeline registration system in pipeline.py attempts to import components like TableRecognizer from ppstructure/ but fails when the doc-parser group is absent.

Fix: Install the specific dependency group matching your use case:

# For table recognition, formula parsing, and layout analysis

python -m pip install "paddleocr[doc-parser]"

# For key-information extraction

python -m pip install "paddleocr[ie]"

# For document translation

python -m pip install "paddleocr[trans]"

# For all optional features

python -m pip install "paddleocr[all]"

Windows 50-Series GPU Wheel Issues

Symptoms: pip install paddlepaddle-gpu succeeds but importing fails with dll load failed on Windows machines with NVIDIA RTX 5000-series cards.

Root cause: The default GPU wheel lacks required AVX-512 instructions for NVIDIA 50-Series hardware.

Fix: Use the dedicated Windows-50-Series wheel referenced in docs/version3.x/installation.md. For Python 3.10, install the specific development wheel:

python -m pip install https://paddle-qa.bj.bcebos.com/paddle-pipeline/Develop-TagBuild-Training-Windows-Gpu-Cuda12.9-Cudnn9.9-Trt10.5-Mkl-Avx-VS2019-SelfBuiltPypiUse/86d658f56ebf3a5a7b2b33ace48f22d10680d311/paddlepaddle_gpu-3.0.0.dev20250717-cp310-cp310-win_amd64.whl
python -m pip install paddleocr

CUDA and TensorRT Incompatibility

Symptoms: ImportError: libtensorrt.so not found, or runtime crashes when use_tensorrt=True.

Root cause: The installed TensorRT version does not align with the PaddlePaddle GPU wheel (e.g., TensorRT 8.6 requires CUDA 11.8).

Fix: Follow the version-specific installation steps in docs/version3.x/installation.md (lines 67-77) to download the correct TensorRT wheel for your selected CUDA version.

Docker Image Version Mismatches

Symptoms: ModuleNotFoundError inside the container despite pip install paddleocr succeeding.

Root cause: The Docker image uses an older PaddlePaddle version (e.g., 3.0.0) while the PaddleOCR code expects 3.2.x APIs.

Fix: Pull the latest image tag (paddlepaddle/paddle:3.2.0 or paddlepaddle/paddle:3.2.0-gpu-cu118) or upgrade the wheel inside the container:

pip install -U paddlepaddle==3.2.0

Network and Proxy Configuration Issues

Symptoms: ConnectionError: HTTPSConnectionPool when running pip install.

Root cause: Corporate firewall blocks access to the PaddlePaddle or PaddleOCR PyPI mirrors.

Fix: Use the Baidu mirror or set proxy environment variables:

python -m pip install paddleocr -i https://mirror.baidu.com/pypi/simple
export HTTPS_PROXY=http://your-proxy:port

Verifying Your Installation

Before running inference, validate that the runtime correctly detects your hardware. The inference scripts in tools/infer_*.py use paddle.get_device() to select execution devices. If PaddlePaddle lacks GPU support, it silently falls back to CPU.

Verification script:

import paddle

print(f"PaddlePaddle version: {paddle.__version__}")
print(f"Detected device: {paddle.get_device()}")

If this outputs cpu when you expected gpu, reinstall the correct paddlepaddle-gpu wheel matching your CUDA version.

Step-by-Step Installation Examples

Basic CPU Installation

python -m pip install paddlepaddle==3.2.0
python -m pip install paddleocr

GPU Installation with Full Features

python -m pip install paddlepaddle-gpu==3.2.0
python -m pip install "paddleocr[all]"

Testing Core OCR Pipelines

Download a sample image and run recognition:

wget https://github.com/PaddlePaddle/PaddleOCR/raw/release/3.2/doc/imgs_en/img_10.jpg
python tools/infer_rec.py -c configs/rec/rec_chinese_common_train_v2.0.yml -i img_10.jpg --use_gpu=False

Testing Table Recognition (Requires doc-parser)

python tools/infer_table.py -c configs/table/ppstructure/table_det.yaml -i img_10.jpg --use_gpu=True

Summary

• Verify PaddlePaddle compatibility: Ensure the wheel version matches your hardware (CPU vs. GPU driver requirements documented in docs/version3.x/installation.md).
• Install optional groups: Use [doc-parser], [ie], or [trans] extras when using ppstructure features to avoid ImportError for TableRecognizer and similar components.
• Use Windows-specific wheels: For RTX 50-Series cards, install the dedicated AVX-512 wheel from the official pipeline instead of the standard paddlepaddle-gpu package.
• Check CUDA/TensorRT alignment: Match TensorRT versions to CUDA requirements (e.g., TensorRT 8.6 for CUDA 11.8) to prevent runtime crashes.
• Validate with paddle.get_device(): Confirm runtime device detection matches your hardware before running inference scripts like tools/infer_rec.py.

Frequently Asked Questions

Why do I get ImportError: cannot import name 'TableRecognizer' after installing paddleocr?

This error occurs because you attempted to use table recognition or document layout features without installing the optional doc-parser dependency group. The base paddleocr package includes only core detection and recognition pipelines. According to the source architecture in ppstructure/, these advanced features require additional dependencies. Install the missing components with python -m pip install "paddleocr[doc-parser]" to access TableRecognizer and related modules.

How do I fix RuntimeError: Paddle compiled with different CUDA version on Linux?

This indicates your installed paddlepaddle-gpu wheel was compiled against a different CUDA version than your system drivers support. Check your NVIDIA driver version with nvidia-smi, then reinstall the specific wheel matching your CUDA version from docs/version3.x/installation.md. For CUDA 11.8, use paddlepaddle-gpu==3.2.0 with driver ≥450.80.02; for CUDA 12.6, ensure driver ≥550.54.14. Mismatches between the wheel and driver cause this runtime compilation error.

Can I use PaddleOCR on Windows with an RTX 5090 GPU?

Yes, but you must use the dedicated Windows-50-Series wheel rather than the standard paddlepaddle-gpu package. The standard wheel lacks AVX-512 instructions required for RTX 5000-series cards. Download the specific .whl file for your Python version from the Paddle pipeline (referenced in docs/version3.x/installation.md) before installing paddleocr. Using the standard wheel results in dll load failed errors during import.

Why does my Docker container show ModuleNotFoundError for paddleocr modules?

The container likely uses an outdated PaddlePaddle base image (e.g., 3.0.0) while PaddleOCR requires 3.2.x APIs, or the paddleocr package was installed on the host but not inside the container. Pull the latest image tag paddlepaddle/paddle:3.2.0 or upgrade PaddlePaddle inside the running container using pip install -U paddlepaddle==3.2.0. Verify that paddleocr itself is installed within the container environment, not just mapped from the host.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}