Prerequisites for Running PaddleOCR: Complete Installation Guide

TLDR: To run PaddleOCR, install Python 3.8–3.12, PaddlePaddle ≥3.0 (e.g., 3.2.0), and the paddleocr package; GPU acceleration requires NVIDIA hardware with CUDA 11.8/12.6 and matching cuDNN versions.

PaddleOCR is a multilingual OCR toolkit built on the PaddlePaddle deep learning framework. Before running inference with the high-level PaddleOCR API or command-line interface, you must configure a compatible software stack and optional hardware accelerators as documented in the PaddlePaddle/PaddleOCR repository.

Software Requirements

Operating System Support

According to docs/quick_start.en.md (lines 7–20), PaddleOCR officially supports Linux, with Windows compatibility available via Docker or WSL, and limited support for macOS.

Python Version Compatibility

The codebase requires Python 3.8 through 3.12. Any minor version within this range is compatible, as specified in docs/quick_start.en.md (lines 9–13).

Core Dependencies

Two primary packages are required:

1. PaddlePaddle: Version ≥3.0 is mandatory because PaddleOCR’s models utilize operators introduced after this release. The current release specifically depends on PaddlePaddle 3.2.0.
2. PaddleOCR: Install via pip using paddleocr[all] for full functionality, or select optional dependency groups such as doc-parser, ie, or trans for specific use cases like document parsing or information extraction.

These requirements are documented in docs/quick_start.en.md (lines 9–35).

Hardware and Acceleration Requirements

CPU-Only Inference

For x86-64 processors, no additional drivers are required. The framework runs on the pure Paddle Inference engine using the "cpu" device type, as referenced in the high-performance inference documentation.

GPU Support and CUDA Versions

For NVIDIA GPU acceleration, you must install a CUDA toolkit and cuDNN version matching your PaddlePaddle build. According to docs/version3.x/deployment/high_performance_inference.en.md (lines 44–66), the supported combinations are:

• CUDA 11.8 with cuDNN 8.9
• CUDA 12.6 with cuDNN 9.5

Full high-performance inference also requires TensorRT 8.6.1.6, though this is only supported with the CUDA 11.8 variant.

Specialized Hardware (XPU and NPU)

For Kunlun XPU or Huawei Ascend NPU support, you must install PaddlePaddle builds specifically compiled for these devices. Instructions are located in docs/version3.x/other_devices_support/paddlepaddle_install_XPU.en.md and paddlepaddle_install_NPU.en.md.

Installing PaddleOCR

Install the core dependencies in a fresh virtual environment:

# Install PaddlePaddle (CPU version)

pip install paddlepaddle==3.2.0

# Or install GPU version (example for CUDA 11.8)

pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

# Install PaddleOCR with all features

pip install "paddleocr[all]"

The paddleocr package exposes the high-level API in paddleocr/__init__.py, including classes like PaddleOCR, PPStructureV3, and PPChatOCRv4. The command-line interface implementation resides in paddleocr/_cli.py.

Configuring High-Performance Inference

To enable optimized inference backends (TensorRT, ONNX Runtime, or OpenVINO), set enable_hpi=True when instantiating the OCR class. First, install hardware-specific dependencies:

# Install HPI dependencies for GPU

paddleocr install_hpi_deps gpu

Then initialize with acceleration:

from paddleocr import PaddleOCR

ocr = PaddleOCR(enable_hpi=True)  # Auto-selects best backend

Model Download Configuration

By default, PaddleOCR pulls pre-trained models from HuggingFace. To force the legacy Baidu BOS endpoint, set the environment variable before running:

export PADDLE_PDX_MODEL_SOURCE=bos

This configuration is referenced in the high-performance inference documentation (lines 23–24).

Verification Example

Verify your installation with a minimal inference script:

from paddleocr import PaddleOCR

# Initialize with optional high-performance inference

ocr = PaddleOCR(enable_hpi=True)

# Run prediction on a sample image

result = ocr.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png")

# Output results

for txt in result:
    txt.print()                # Print text with confidence

    txt.save_to_img("output")  # Save visualization

    txt.save_to_json("output") # Save structured JSON

Summary

• Operating System: Linux (preferred), Windows via Docker/WSL, or macOS
• Python: Versions 3.8 through 3.12 are supported
• Core Stack: Install PaddlePaddle ≥3.0 (e.g., 3.2.0) and the paddleocr package
• GPU Acceleration: Requires NVIDIA GPU with CUDA 11.8/cuDNN 8.9 or CUDA 12.6/cuDNN 9.5; TensorRT 8.6.1.6 optional for CUDA 11.8
• Specialized Hardware: XPU and NPU require device-specific PaddlePaddle builds
• High-Performance Mode: Use enable_hpi=True and run paddleocr install_hpi_deps for optimized backends

Frequently Asked Questions

What Python versions are compatible with PaddleOCR?

PaddleOCR supports Python 3.8, 3.9, 3.10, 3.11, and 3.12. The documentation in docs/quick_start.en.md explicitly lists this range, and any minor version within these bounds will function correctly with the current PaddlePaddle 3.2.0 dependency.

Do I need a GPU to run PaddleOCR?

No, a GPU is optional. CPU-only inference works on any x86-64 processor without additional drivers. However, GPU acceleration significantly improves throughput for document analysis and high-resolution image processing.

How do I enable TensorRT acceleration in PaddleOCR?

First, ensure you are using the CUDA 11.8 build of PaddlePaddle and have installed TensorRT 8.6.1.6. Then run paddleocr install_hpi_deps gpu to configure the native libraries. Finally, instantiate the PaddleOCR class with enable_hpi=True to allow automatic backend selection.

Can I run PaddleOCR on macOS or Windows?

Yes, though Linux is the officially supported platform. Windows users should deploy via Docker or WSL2 to ensure compatibility. macOS is supported for development and inference, but GPU acceleration options are limited compared to Linux environments.

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