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

> Solve common PaddleOCR installation errors. Verify compatibility, install dependencies, and optimize GPU acceleration for a smooth setup.

- Repository: [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/tools/infer_det.py), [`tools/infer_rec.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/tools/infer_rec.py), and [`tools/infer_cls.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/tools/infer_cls.py). These components function with the base installation and require no extra dependencies beyond the core framework and [`requirements.txt`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/setup.cfg) or [`pyproject.toml`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/installation.md). Verify your driver compatibility before selecting the CPU, GPU, or Windows-50-Series wheel.

```python
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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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:

```bash

# 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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/installation.md). For Python 3.10, install the specific development wheel:

```powershell
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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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:

```bash
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:

```bash
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**:

```python
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

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

```

### GPU Installation with Full Features

```bash
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:

```bash
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`)

```bash
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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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.