Install PaddleOCR 3.7 — the commands that actually work

Install command builder#

How the pieces fit together#

Since PaddleOCR 3.x, the paddleocr package doesn't bring its own runtime. It's a thin layer over PaddleX (which it installs automatically, version 3.7.x for PaddleOCR 3.7) and runs models on whichever inference engine you install separately:¹³

If you skip the engine, the default pipeline fails at the first prediction with "Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed." That's the most common first-run error — and the fix is simply step 2 below.

The engine parameter accepts "paddle", "paddle_static", "paddle_dynamic", "transformers" and "onnxruntime". Leave it unset and PaddleOCR uses PaddlePaddle in most cases. Keep one engine per environment: the docs warn that their dependencies can conflict.³

CPU install (Linux, Windows, macOS)#

1. Create a clean environment#

   Linux / macOSWindows

   Copy

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip

   py -3.12 -m venv .venv
   .venv\Scripts\activate
   python -m pip install --upgrade pip

2. Install a pinned engine#

   $python -m pip install paddlepaddle==3.2.0Copy

   This is the version the official installation guide pins (the guide installs it from paddlepaddle.org.cn; PyPI also publishes 3.2.0 wheels for Python 3.9–3.13 on Linux x86-64, Linux ARM64, Windows and Apple Silicon, and that's what we used).¹²

3. Install PaddleOCR#

   $python -m pip install paddleocr==3.7.0Copy

   Add an extra if you need more than text OCR: "paddleocr[doc-parser]" for PP-StructureV3 and PaddleOCR-VL, "paddleocr[all]" for everything, "paddleocr[doc2md]" for Word/Excel/PowerPoint to Markdown.

4. Run it#

   $paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png --save_path ./outputCopy

   The first run downloads PP-OCRv6 medium (about 139 MB on disk for detection and recognition together in our install) into ~/.paddlex/official_models. Later runs start in seconds.

CPU install with ONNX Runtime (fastest in our test)#

PaddleOCR 3.5 added ONNX Runtime as an engine. On our 4-vCPU test machine it ran every PP-OCRv6 tier 1.4–1.5× faster than PaddlePaddle 3.2.0 and produced identical text. The official docs only document onnxruntime-gpu for NVIDIA CUDA 12.x; for CPU, the regular onnxruntime package is what we used.³⁷

python -m pip install paddleocr==3.7.0 onnxruntime
paddleocr ocr -i receipt.jpg --engine onnxruntime --save_path ./output

from paddleocr import PaddleOCR

ocr = PaddleOCR(engine="onnxruntime")   # downloads the *_onnx model variants
result = ocr.predict("receipt.jpg")
print(result[0]["rec_texts"])

We verified this in a fresh environment containing only paddleocr 3.7.0 and onnxruntime 1.31.1 — no PaddlePaddle at all — for both the Python API and the CLI. Expect a burst of yellow [W:onnxruntime ... Removing initializer ...] lines on first load: they're harmless graph-optimisation warnings, not errors.

NVIDIA GPU install#

PaddlePaddle 3.x GPU wheels are not on PyPI. The newest paddlepaddle-gpu on PyPI is 2.6.2 from September 2024, and PaddleOCR 3.x needs PaddlePaddle 3.0 or newer. Install from the official index for your driver:¹²

Only the driver version matters — the docs are explicit that the CUDA toolkit installed on the machine doesn't. Check your driver with nvidia-smi, then confirm PaddlePaddle sees the GPU:

python -c "import paddle; print(paddle.is_compiled_with_cuda())"   # must print True
paddleocr ocr -i receipt.jpg --device gpu:0

In Python, select the device with PaddleOCR(device="gpu:0"). The 2.x argument use_gpu=True no longer exists and raises ValueError: Unknown argument: use_gpu — see the migration guide.

macOS (Apple Silicon and Intel)#

PyPI ships Apple Silicon (macosx_11_0_arm64) PaddlePaddle wheels for every 3.x release, so the CPU commands above work unchanged on M1–M4 Macs. There is no CUDA on macOS, so leave device at its default. The official PaddleOCR-VL guide for Apple Silicon says accuracy and speed were verified on an M4, that only the PaddlePaddle engine is supported there, and that the official Docker image doesn't run on Apple Silicon.²

Intel Macs are a different story: PyPI's last x86-64 macOS wheel is PaddlePaddle 3.0.0. That version meets PaddleOCR 3.x's documented minimum, but we haven't tested it on an Intel Mac. The builder above pins it for you when you choose macOS (Intel).

Windows#

• Use the py launcher and a venv (see step 1). The commands are otherwise identical to Linux.
• RTX 50-series GPUs need the special wheels described in the GPU table.
• High-performance inference (enable_hpi) isn't supported directly on Windows; the docs recommend Docker or WSL for it.⁵

Docker#

The official images live on Baidu's registry. For PaddleOCR-VL there is a ready-to-run image (about 8 GB, or about 10 GB for the -offline variant with models bundled), which needs Docker 19.03+ and an NVIDIA driver supporting CUDA 12.6+:⁶

docker run -it --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu /bin/bash

For text OCR and PP-StructureV3 the docs don't provide a dedicated PaddleOCR image. A minimal image using the same pinned packages we tested works like this (this Dockerfile is our example, not an official one):

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
 && rm -rf /var/lib/apt/lists/*
RUN python -m pip install --no-cache-dir paddlepaddle==3.2.0 paddleocr==3.7.0
# optional: bake models into the image so containers start offline
RUN python -c "from paddleocr import PaddleOCR; PaddleOCR()"

The libgl1 line prevents the classic ImportError: libGL.so.1 on slim images. Don't "fix" that error by swapping in opencv-python-headless: PaddleX checks for opencv-contrib-python by name, so the swap breaks the OCR pipeline. Why.

Google Colab and Kaggle#

!pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
!pip install "paddleocr[doc-parser]==3.7.0"

!pip install paddlepaddle==3.2.0 "paddleocr==3.7.0"

Restart the runtime after installing, then run from paddleocr import PaddleOCR.

Python version support#

We ran everything on this site with Python 3.13. If you want every optional feature, Python 3.10–3.12 is the safest choice.²⁵

Model downloads, cache and offline use#

Models download on first use to ~/.paddlex/official_models/<model_name>. Set PADDLE_PDX_CACHE_HOME to move the cache. The default source is Hugging Face; set PADDLE_PDX_MODEL_SOURCE to bos (Baidu), modelscope or aistudio if Hugging Face is slow or blocked where you are.⁴

export PADDLE_PDX_MODEL_SOURCE=bos          # Windows: set PADDLE_PDX_MODEL_SOURCE=bos
export PADDLE_PDX_CACHE_HOME=/data/paddlex  # optional: move the model cache

For air-gapped machines, copy the model folders from a connected machine into the same cache path, or point the pipeline at local folders with text_detection_model_dir and text_recognition_model_dir.

Two source-code details the docs don't mention: PaddleX checks each model host's reachability before downloading, and setting PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK skips that check — but it's read as a raw string, so any non-empty value, even 0 or false, turns the check off.⁴

Verify the install#

python -c "import paddleocr; print(paddleocr.__version__)"   # 3.7.0
python -c "import paddle; print(paddle.__version__)"         # 3.2.0
python -c "import paddle; paddle.utils.run_check()"           # "PaddlePaddle is installed successfully!"

Upgrading from PaddleOCR 2.x#

3.x is not backward compatible: ocr(img, cls=True), use_gpu, use_angle_cls, draw_ocr and PPStructure are gone or renamed. Paste your old code into our 2.x → 3.x converter to see exactly what to change. If you must keep 2.x for now, pin it: pip install "paddleocr<3".

Installation FAQ#