PaddleOCR 3.7 のインストール — 確実に動くコマンド

インストールコマンド生成#

各コンポーネントの関係#

PaddleOCR 3.x 以降、paddleocr パッケージは独自のランタイムを同梱していません。PaddleX（自動でインストールされ、PaddleOCR 3.7 では 3.7.x）の上に載る薄いレイヤーで、別途インストールした推論エンジンでモデルを実行します。¹³

エンジンを入れずに実行すると、標準パイプラインは最初の推論で "Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed." というエラーで失敗します。初回実行時に最も多いエラーですが、下の手順 2 を行えば解決します。

engine パラメータには "paddle"、"paddle_static"、"paddle_dynamic"、"transformers"、"onnxruntime" を指定できます。指定しない場合、ほとんどのケースで PaddlePaddle が使われます。公式ドキュメントは依存関係が衝突する可能性を警告しているため、1 つの環境に入れるエンジンは 1 つにしてください。³

CPU 版のインストール（Linux・Windows・macOS）#

1. クリーンな仮想環境を作る#

   Linux / macOSWindows

   コピー

   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. バージョンを固定してエンジンをインストール#

   $python -m pip install paddlepaddle==3.2.0コピー

   公式インストールガイドが指定しているバージョンです（ガイドでは paddlepaddle.org.cn からインストールしていますが、PyPI でも Linux x86-64、Linux ARM64、Windows、Apple Silicon 向けに Python 3.9〜3.13 の 3.2.0 wheel が公開されており、私たちはそちらを使いました）。¹²

3. PaddleOCR をインストール#

   $python -m pip install paddleocr==3.7.0コピー

   テキスト OCR 以外の機能が必要な場合は extra を追加します。PP-StructureV3 と PaddleOCR-VL には "paddleocr[doc-parser]"、すべての機能には "paddleocr[all]"、Word・Excel・PowerPoint から Markdown への変換には "paddleocr[doc2md]" です。

4. 実行する#

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

   初回実行時に PP-OCRv6 medium（私たちの環境では検出・認識モデルを合わせてディスク上で約 139 MB）が ~/.paddlex/official_models にダウンロードされます。2 回目以降は数秒で起動します。

ONNX Runtime を使った CPU 版のインストール（テストで最速）#

PaddleOCR 3.5 で、エンジンとして ONNX Runtime が追加されました。4 vCPU のテスト機では、PP-OCRv6 の全ティアが PaddlePaddle 3.2.0 より 1.4〜1.5 倍速く動作し、出力テキストも同一でした。公式ドキュメントに記載があるのは NVIDIA CUDA 12.x 向けの onnxruntime-gpu だけですが、CPU では通常の onnxruntime パッケージを使いました。³⁷

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"])

paddleocr 3.7.0 と onnxruntime 1.31.1 だけを入れた（PaddlePaddle を含まない）新しい環境で、Python API と CLI の両方の動作を確認しました。初回読み込み時には黄色の [W:onnxruntime ... Removing initializer ...] という行が大量に出ますが、グラフ最適化に関する無害な警告で、エラーではありません。

NVIDIA GPU 版のインストール#

PaddlePaddle 3.x の GPU 版 wheel は PyPI にありません。PyPI にある最新の paddlepaddle-gpu は 2024年9月の 2.6.2 で、PaddleOCR 3.x には PaddlePaddle 3.0 以降が必要です。お使いのドライバーに合わせて、公式インデックスからインストールしてください。¹²

重要なのはドライバーのバージョンだけです。マシンにインストールされている CUDA Toolkit は関係ないと、公式ドキュメントに明記されています。nvidia-smi でドライバーを確認し、PaddlePaddle が GPU を認識しているか確かめてください。

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

Python では PaddleOCR(device="gpu:0") でデバイスを指定します。2.x の引数 use_gpu=True は廃止されており、ValueError: Unknown argument: use_gpu になります。詳しくは移行ガイドをご覧ください。

macOS（Apple Silicon と Intel）#

PyPI では 3.x のすべてのリリースで Apple Silicon（macosx_11_0_arm64）向けの PaddlePaddle wheel が公開されているため、M1〜M4 の Mac でも上記の CPU 用コマンドがそのまま使えます。macOS には CUDA がないので、device は既定値のままにしてください。公式の Apple Silicon 向け PaddleOCR-VL ガイドによると、精度と速度は M4 で検証済みで、対応するのは PaddlePaddle エンジンのみ、公式 Docker イメージは Apple Silicon では動作しないとされています。²

Intel Mac は事情が異なります。PyPI で x86-64 macOS 向けの最後の wheel は PaddlePaddle 3.0.0 です。PaddleOCR 3.x の最低要件は満たしていますが、私たちは Intel Mac では検証していません。上のツールで macOS（Intel）を選ぶと、このバージョンに自動で固定されます。

Windows#

• py ランチャーと venv を使ってください（手順 1 を参照）。それ以外のコマンドは Linux と同じです。
• RTX 50 シリーズの GPU には、GPU の表で説明した専用 wheel が必要です。
• 高性能推論（enable_hpi）は Windows では直接サポートされていません。公式ドキュメントは Docker か WSL の利用を推奨しています。⁵

Docker#

公式イメージは Baidu のレジストリで公開されています。PaddleOCR-VL にはすぐに使えるイメージ（約 8 GB、モデル同梱の -offline 版は約 10 GB）があり、Docker 19.03 以降と CUDA 12.6 以降に対応した NVIDIA ドライバーが必要です。⁶

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

テキスト OCR と PP-StructureV3 については、公式ドキュメントに専用の PaddleOCR イメージはありません。私たちが検証したのと同じ固定バージョンのパッケージを使う最小構成のイメージは、次のように作れます（この Dockerfile は私たちの例であり、公式のものではありません）。

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()"

libgl1 の行は、slim イメージでおなじみの ImportError: libGL.so.1 を防ぎます。このエラーを opencv-python-headless への置き換えで「直す」のはやめてください。PaddleX は opencv-contrib-python をパッケージ名で確認するため、置き換えると OCR パイプラインが動かなくなります。理由

Google Colab と 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"

インストール後にランタイムを再起動してから、from paddleocr import PaddleOCR を実行してください。

対応する Python のバージョン#

本サイトの検証はすべて Python 3.13 で行いました。オプション機能をすべて使いたい場合は、Python 3.10〜3.12 が最も無難です。²⁵

モデルのダウンロード、キャッシュ、オフライン利用#

モデルは初回使用時に ~/.paddlex/official_models/<model_name> にダウンロードされます。キャッシュの場所を変えるには PADDLE_PDX_CACHE_HOME を設定します。既定の取得元は Hugging Face です。Hugging Face が遅い、またはアクセスできない場合は、PADDLE_PDX_MODEL_SOURCE を bos（Baidu）、modelscope、aistudio のいずれかに設定してください。⁴

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

インターネットに接続できないマシンでは、接続できるマシンからモデルのフォルダーを同じキャッシュパスにコピーするか、text_detection_model_dir と text_recognition_model_dir でローカルのフォルダーを指定してください。

ドキュメントに書かれていないソースコード上の挙動が 2 つあります。PaddleX はダウンロード前に各モデルホストへの到達性を確認し、PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK を設定するとこの確認を省略します。ただしこの値は文字列のまま読まれるため、空でなければ 0 や false であっても確認が無効になります。⁴

インストールの確認#

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!"

PaddleOCR 2.x からのアップグレード#

3.x には後方互換性がありません。ocr(img, cls=True)、use_gpu、use_angle_cls、draw_ocr、PPStructure は廃止または名称変更されています。旧コードを 2.x → 3.x 変換ツールに貼り付ければ、変更箇所が正確にわかります。当面 2.x を使い続ける必要がある場合は、pip install "paddleocr<3" でバージョンを固定してください。

インストールに関するよくある質問#