# Prerequisites for Running PaddleOCR: Complete Installation Guide

> Learn the essential prerequisites for running PaddleOCR. Install Python, PaddlePaddle, and the paddleocr package. Explore GPU acceleration with CUDA and cuDNN for faster performance.

- Repository: [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- Tags: getting-started
- Published: 2026-03-03

---

**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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/other_devices_support/paddlepaddle_install_XPU.en.md) and [`paddlepaddle_install_NPU.en.md`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddlepaddle_install_NPU.en.md).

## Installing PaddleOCR

Install the core dependencies in a fresh virtual environment:

```bash

# 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`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/__init__.py), including classes like `PaddleOCR`, `PPStructureV3`, and `PPChatOCRv4`. The command-line interface implementation resides in [`paddleocr/_cli.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/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:

```bash

# Install HPI dependencies for GPU

paddleocr install_hpi_deps gpu

```

Then initialize with acceleration:

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

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

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