Install PaddleOCR 3.6: Modern OCR AI Deploy Guide

Two ways to get modern OCR AI running on your machine with PaddleOCR. One of them you should probably skip.

Option A: clone the GitHub repo, install from source, manage your own dependencies. Option B: pip install paddleocr from PyPI and let the wheel handle everything. Unless you’re modifying training code or contributing PRs, Option B wins – it pins compatible versions, ships the model loaders, and saves you from the dependency rabbit hole that source installs invite. The official installation docs recommend the pip route for inference. Source is for contributors.

This guide deploys PaddleOCR 3.6.0 – the current PyPI release as of this writing – locally, with the modular dependency groups introduced in 3.5 that most tutorials still ignore.

Why PaddleOCR is worth deploying

It’s a document-to-structured-data toolkit, not just a text reader. With 70k+ Stars and trusted by top-tier projects like Dify, RAGFlow, and Cherry Studio, PaddleOCR sits underneath a lot of RAG infrastructure you’ve probably touched. The flagship VLM is small and accurate: PaddleOCR-VL-1.6 achieves a new state-of-the-art score of 96.33% on the authoritative benchmark OmniDocBench v1.6, released by the team on May 28, 2026.

The catch nobody warns you about: PaddleOCR 3.x introduces several significant interface changes. Old code written based on PaddleOCR 2.x is likely incompatible with PaddleOCR 3.x. If you’re following a 2023 Medium tutorial, stop now – the API has moved.

System requirements

Per the official installation guide, here’s what you actually need:

The Python 3.8 line has a sharp edge to it. paddleocr itself and the doc2md dependency group support Python 3.8 and later. The other optional dependency groups (doc-parser, ie, trans, all) require Python 3.9 or later due to upstream dependencies. If you plan to parse documents (not just read text), use 3.9 minimum. Save yourself the rebuild.

Step-by-step install

Open a clean virtual environment. Always a clean venv – mixing PaddleOCR into an existing project’s site-packages is how you discover dependency hell.

python -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate
python -m pip install --upgrade pip

Now pick your install scope. Default capabilities only: general OCR and document image preprocessing. python -m pip install paddleocr. All optional capabilities: document parsing, document understanding, document translation, key information extraction. Use brackets to enable groups:

# Just text detection + recognition
pip install paddleocr

# Everything (doc parsing, KIE, translation)
pip install "paddleocr[all]"

# Or a specific capability
pip install "paddleocr[doc-parser]"

Next, the inference engine. CPU works fine for testing; for production throughput you want GPU. Since GPU installation requires specific CUDA versions, the following example is for installing NVIDIA GPU on the Linux platform with CUDA 11.8. For other platforms, please refer to the instructions in the PaddlePaddle official installation documentation. python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

For CPU:

python -m pip install paddlepaddle==3.2.0

Pro tip: Add --default-timeout=100 to any paddlepaddle-gpu install command. The default 15-second pip timeout chokes on the nvidia-cufft-cu12 wheel – it’s hundreds of megabytes, and the official Paddle index sits behind variable-latency CDN. This single flag prevents the most-reported install failure.

First-time configuration

PaddleOCR 3.x downloads models on first call. By default it pulls from Hugging Face – The default download source has been changed from BOS to HuggingFace. Users can also change the environment variable PADDLE_PDX_MODEL_SOURCE to BOS to set the model download source back to Baidu Object Storage (BOS). If you’re behind a firewall that blocks HF but allows BOS (common in mainland China deployments), set it before first run:

export PADDLE_PDX_MODEL_SOURCE=BOS

Minimum viable test config – drop this in test_ocr.py:

from paddleocr import PaddleOCR

ocr = PaddleOCR(
 use_doc_orientation_classify=False,
 use_doc_unwarping=False,
 use_textline_orientation=False,
 lang="en",
)
result = ocr.predict("sample.png")
for item in result:
 item.print()

Verify it works

Two checks. First, version sanity:

python -c "import paddleocr; print(paddleocr.__version__)"
python -c "import paddle; print(paddle.__version__); paddle.utils.run_check()"

The run_check() call is the one that actually matters. It runs a tiny forward pass on whatever device Paddle thinks it has. If it says “PaddlePaddle is installed successfully!” you’re good. If it complains about CUDA, you’ve got a driver-toolkit mismatch – not an OCR problem.

CLI smoke test:

paddleocr ocr -i sample.png --lang en

Common errors and the fixes that actually work

These are pulled from real GitHub threads – not invented scenarios.

• ReadTimeoutError on nvidia-cufft-cu12. The fix from Discussion #14556: re-run with --default-timeout=100, or download the failing wheel manually from paddle-whl.bj.bcebos.com and pip install the local file.
• “Could not find a version that satisfies the requirement paddlepaddle==3.0.0rc1”. Per Issue #15134, the RC tag was pulled after stable release. Use the stable version (3.0.0, 3.1.0, or 3.2.0) instead of any rc/beta tag you copied from an older blog post.
• AttributeError: partially initialized module ‘paddle’ has no attribute ‘pir’. Circular import, usually because a file in your project is literally named paddle.py or because you mixed paddleocr 3.0 with paddlepaddle < 3.0. Rename the file or upgrade Paddle.
• Python 3.12 traceback through paddlex pp_option.py. Missing setuptools in fresh environments – install it first: pip install setuptools wheel, then install paddleocr.
• Conflicting dependency errors during pip resolution. The official FAQ’s escape hatch: Install with specific versions: pip install paddleocr==3.2.0 –no-deps, then install dependencies separately. Ugly, but it works when the resolver gets stuck.

The Transformers backend route (the option most guides miss)

Here’s a thing the tutorials skip. PaddleOCR 3.5 uses a unified inference-engine configuration and can use backends such as PaddlePaddle and Transformers. You can run PaddleOCR-VL through Hugging Face Transformers without installing the PaddlePaddle framework at all.

pip install paddleocr transformers torch

This matters in two scenarios: your environment already has PyTorch and you don’t want a second 1+ GB framework, or you’re targeting Apple Silicon where PaddlePaddle GPU support is less mature. The trade-off is fewer optimizations – Paddle’s high-performance inference path supports CUDA 12 and ONNX Runtime, which the Transformers route doesn’t reach.

Upgrading from 2.x or older 3.x

If you’re on 2.x, treat this as a rewrite, not an upgrade. The API surface changed enough that PaddleOCR() constructor arguments differ. Read the 3.x upgrade notes before touching production code.

From 3.0 → 3.6 is straightforward:

pip install --upgrade paddleocr paddlepaddle
# or for GPU:
pip install --upgrade paddleocr
pip install --upgrade paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

Uninstall

Clean removal in three commands:

pip uninstall paddleocr paddlepaddle paddlepaddle-gpu paddlex
rm -rf ~/.paddlex # cached models
rm -rf ~/.paddleocr # legacy 2.x cache, if present

The model cache is the part everyone forgets. PaddleOCR-VL weights are around a gigabyte each – leaving them behind eats disk for no reason if you’re done with the tool.

FAQ

Do I need a GPU to run PaddleOCR?

No. CPU inference works for PP-OCRv5 mobile models and is honestly fine for under a few pages a second. The VL models are the ones that really want a GPU.

Why does paddleocr hang on first run with no output?

It’s silently downloading models. On a slow connection, the VL weights can take several minutes and there’s no progress bar in some pipeline modes. If you’ve waited five minutes with no error and no output, it’s still downloading – check your ~/.paddlex directory size growing. To verify, run with verbose logging or pre-download via the CLI before integrating into a script. If you’re in a restricted network, switch the source by setting PADDLE_PDX_MODEL_SOURCE=BOS or use AIStudio/ModelScope mirrors.

Is PaddleOCR safe for commercial use?

Yes – it’s Apache 2.0. Keep the license notice and you’re free to ship it in commercial products. No usage-based fees, no API key.

Your next move: run pip install "paddleocr[doc-parser]" in a fresh Python 3.10 venv, then test it on a single PDF you actually care about. If parsing works on that one file, the install is real. Then scale up.