PaddleOCR のエラーと解決方法

エラー解決ツール#

各項目の根拠は、PaddleOCR・PaddleX・PaddlePaddle のソースコード（ファイルと行を明記）か、私たちのテスト機での実行結果（paddleocr.dev で再現済みと表示）のどちらかです。公式ドキュメントの助言が 3.x では通用しなくなっている場合は、その旨を記載しています。全項目を下にも掲載しているので、個別にリンクできます。なお、ツールが表示する結果の文章は英語です。⁹

ConvertPirAttribute2RuntimeAttribute not support pir::ArrayAttribute（oneDNN のクラッシュ）#

paddleocr.dev で再現済み CPU マシンで素直なインストール手順（pip install paddleocr paddlepaddle）を実行し、何かを OCR すると、現在はこのエラーになります。¹

NotImplementedError: (Unimplemented) ConvertPirAttribute2RuntimeAttribute not support [pir::ArrayAttribute<pir::DoubleAttribute>]  (at /paddle/paddle/fluid/framework/new_executor/instruction/onednn/onednn_instruction.cc:116)

原因#

3 つの事実が重なっています。pip install paddlepaddle では PyPI の最新リリースである 3.3.1 が入ります。⁸ PaddleOCR 3.x は CPU で oneDNN（MKL-DNN）を既定で有効にします（enable_mkldnn=True）。⁴ そして PaddlePaddle の oneDNN 実行器にある関数 ConvertPirAttribute2RuntimeAttribute には、タグ付きリリース v3.3.0、v3.3.1、v3.4.0 で double の配列型の属性を扱う分岐がなく、116 行目で Unimplemented を送出します。develop ブランチにはこの分岐が追加されていますが、私たちが確認したタグ付きリリースには含まれていません。³ PaddleOCR の公式ドキュメントはこのエラーに触れていませんが、paddlepaddle==3.2.0 に固定しているため、ドキュメントどおりに進めた人はこの問題に遭遇しません。⁶

有効な 3 つの解決策#

同じマシン、同じ文書で、それぞれを試しました。¹²

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
# then run your code unchanged

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', enable_mkldnn=False)
# CLI: paddleocr ocr -i img.png --enable_mkldnn False

# pip install onnxruntime   (PaddlePaddle is not needed at all for this engine)
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', engine='onnxruntime')

• A は oneDNN を維持でき、インストールガイドが指定するバージョンと一致します。コードの変更は不要です。
• B は最も遅い方法です。CPU の実行モードを oneDNN から通常の paddle に切り替えます。私たちのマシンでは 1 ページあたり平均 11.88 秒で、PaddlePaddle 3.2.0 の oneDNN（4.51 秒）に比べて平均 2.6 倍、文書によって 2.3〜3.0 倍遅くなりました。
• C は最速でした（既定の PP-OCRv6 モデルで 1 ページ 2.92 秒）。pip install paddleocr onnxruntime だけで動作します。初回読み込み時に無害な Removing initializer の警告が大量に出ます。同じベンチマークでの注意点として、PP-OCRv5_server のモデルでは ONNX Runtime が大幅に遅くなりました（1 ページあたり 35.70 秒 vs 5.25 秒）。

3 つの構成とも正解 124 項目中 123 項目を完全に読み取ったので、選択の基準は精度ではなく速度です。測定方法の詳細はベンチマークのページ (EN) に、OS ごとのバージョン固定コマンドはインストールガイドにあります。develop ブランチの修正を含む PaddlePaddle がリリースされれば、アップグレードが 4 つ目の選択肢になります。その際はこのページを更新します。

A dependency error occurred during pipeline creation#

paddleocr.dev で再現済み 単に pip install paddleocr を実行した環境で PPStructureV3() を呼ぶと、このエラーになりました。¹

RuntimeError: A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.

このメッセージからは何が足りないのかわかりません。本当の原因は、トレースバックで「The above exception was the direct cause of the following exception」の行より上に表示されている例外です。

DependencyError: `PP-StructureV3` requires additional dependencies. To install them, run `pip install "paddlex[ocr]==<PADDLEX_VERSION>"` if you're installing `paddlex` from an index, or `pip install -e "/path/to/PaddleX[ocr]"` if you're installing `paddlex` locally.

基本の pip install paddleocr で入るのは paddlex[ocr-core] だけです。文書解析には doc-parser extra が必要で、これが paddlex[ocr,genai-client] を導入します。⁴ メッセージにあるように PaddleX を手動でインストールする必要はなく、PaddleOCR の extra をインストールしてください。

必須パッケージが置き換えられたり削除されたりした場合は、基本の OCR でも同じエラーが出ます。PaddleX は importlib.metadata を使い、インストール済みのディストリビューションを名前で確認しているためです。⁵ その典型的な原因が OpenCV を headless 版に入れ替えることです。下の libGL を参照してください。

Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed#

RuntimeError: Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed.

pip install paddleocr では PaddlePaddle はインストールされません。依存パッケージは paddlex[ocr-core]、PyYAML、requests、aiohttp、typing-extensions です。engine を指定しない場合、PaddleX は PaddlePaddle エンジンを選び、paddle モジュールの有無を確認します。⁴⁵ 推論エンジンを 1 つインストールしてください。

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -c "import paddle; print(paddle.__version__)"

# driver >= 550.54.14
python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
# older driver (>= 450.80.02 on Linux, >= 452.39 on Windows): use .../stable/cu118/

python -m pip install onnxruntime
# then: PaddleOCR(engine='onnxruntime')

CPU では 3.2.0 に固定してください。バージョンを指定しない pip install paddlepaddle では 3.3.1 が入り、oneDNN のクラッシュが起きます。GPU 版の 3.x wheel を入手できるのは PaddlePaddle のインデックスだけです。PyPI の paddlepaddle-gpu は 2.6.2 で止まっており、PaddleOCR 3.x では使えません。⁸⁶ 公式ドキュメントでは、wheel はマシンにインストールされた CUDA Toolkit ではなく、GPU ドライバーのバージョンで選ぶよう説明しています。1 つの環境に入れるエンジンは 1 つだけにしてください。

ImportError: libGL.so.1: cannot open shared object file#

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

slim 系の Docker イメージや最小構成の Linux サーバーで発生します。PaddleX の OCR 依存関係には opencv-contrib-python==4.10.0.84（headless ではない通常の OpenCV）が含まれており、システムの libGL と glib にリンクしています。⁵ これらのライブラリをインストールしてください。PaddleOCR 自身の Dockerfile でも同じことをしています。⁷

apt-get update && apt-get install -y libgl1 libglib2.0-0

libgthread-2.0.so.0 や libglib-2.0.so.0 のエラーも glib パッケージに由来するもので、同じ方法で解決します。

PaddleOCR が GPU を使わない#

PaddleOCR 3.x は GPU を使えなくてもエラーにはなりません。device='gpu' を指定していても、インストールされた PaddlePaddle が CUDA 非対応なら、PaddleX は 1 行のログを出して CPU で処理を続けます。⁵

The specified device (GPU) is not available! Switching to CPU instead.

PADDLE_PDX_DISABLE_DEVICE_FALLBACK を設定すると、この場合に RuntimeError を送出させることができます。よくある原因は CPU 版の PaddlePaddle です。pip install paddlepaddle や pip install paddleocr だけでは GPU 対応にはならず、PyPI からの pip install paddlepaddle-gpu では 2.6.2 が入ります。現在の状態を確認してください。

python -c "import paddle; print(paddle.__version__, paddle.is_compiled_with_cuda(), paddle.device.cuda.device_count())"
nvidia-smi

1. False と表示された場合：pip uninstall paddlepaddle paddlepaddle-gpu を実行し、ドライバーのバージョンに応じて上記の cu126 または cu118 のインデックスから paddlepaddle-gpu==3.2.0 をインストールします。
2. True と表示されてもデバイス数が 0 の場合は、PaddlePaddle が GPU を認識できていません。nvidia-smi に GPU が表示されるか確認してください。
3. device='gpu' または 'gpu:0' を使います。'cuda' は AssertionError で拒否されます。
4. 2.x の書き方である use_gpu=True は、3.x では ValueError: Unknown argument: use_gpu になります（後述）。

engine='onnxruntime' で GPU を使うには、onnxruntime-gpu（CUDA 12）とその CUDAExecutionProvider が必要です。ライブラリの読み込みエラー（libcudnn、libcublas）や Windows の RTX 50 シリーズについては、下の GPU の節で扱います。

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

Unknown argument: use_gpu#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: use_gpu

原因：2.x のエンジンオプション use_gpu / gpu_id / gpu_mem は 3.x には存在しません。クラスが処理しないキーワード引数はすべて、device、engine、engine_config、enable_hpi、use_tensorrt、precision、enable_mkldnn、mkldnn_cache_capacity、cpu_threads、enable_cinn のいずれかであるかを検証されます。

1. use_gpu / gpu_id / gpu_mem を削除します。
2. ハードウェアは device='gpu'、device='gpu:1'、device='cpu' で指定します。
3. device を省略すると、Paddle が CUDA GPU を認識していれば GPU 0、そうでなければ CPU が使われます。

# 2.x
ocr = PaddleOCR(use_gpu=True, lang='en')
# 3.x
ocr = PaddleOCR(device='gpu', lang='en')

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_common_args.py:38-50; paddlex-3.7.2/paddlex/utils/device.py:55-75; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1094-1111

Unknown argument: show_log#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: show_log

原因：show_log は廃止されました。3.x では共通の 'paddleocr' ロガー（既定のレベルは ERROR）を使います。

1. show_log=... を削除します。
2. 出力の詳しさを変えるには：import logging; from paddleocr import logger; logger.setLevel(logging.INFO)

import logging
from paddleocr import PaddleOCR, logger
logger.setLevel(logging.ERROR)  # replaces show_log=False
ocr = PaddleOCR(lang='en')

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:69; PaddleOCR/docs/version3.x/logging.en.md:9-24; PaddleOCR/paddleocr/_utils/logging.py:24-36

Unknown argument: use_onnx#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: use_onnx

原因：use_onnx は高性能推論（enable_hpi）に置き換えられ、3.5 以降は engine／engine_config の仕組みに置き換えられました。

1. use_onnx を削除します。
2. enable_hpi=True（高性能推論プラグイン）を指定するか、pip install onnxruntime（CPU）／onnxruntime-gpu（CUDA 12）を実行したうえで engine='onnxruntime' を指定します。
3. ONNX Runtime のオプションは engine_config に渡します。例：engine_config={'providers': ['CUDAExecutionProvider']}

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:71; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:20-30,50-58,118-132

Unknown argument: drop_score#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: drop_score

原因：drop_score は 3.x の非推奨名の対応表に含まれていません。相当するのは text_rec_score_thresh です（既定値は 3.x で 0.0、2.x では 0.5）。

1. drop_score=0.5 を text_rec_score_thresh=0.5 に書き換えます（コンストラクタでも predict() でも可）。

ocr = PaddleOCR(text_rec_score_thresh=0.5)

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,90,191; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:107; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:45

Unknown argument: <その他の 2.x オプション>#

ValueError: Unknown argument: {name}

原因：自動で対応付けられる旧名は 11 個だけで（use_angle_cls、det_model_dir、det_limit_side_len、det_limit_type、det_db_thresh、det_db_box_thresh、det_db_unclip_ratio、rec_model_dir、rec_batch_num、cls_model_dir、cls_batch_num）、それも PaddleOCR クラスに限られます。それ以外の 2.x のキーワード引数はすべてエラーになります。

1. 移行対応表（migration.json）でその名前を調べます。
2. rec_image_shape -> text_rec_input_shape、use_xpu/use_npu -> device='xpu'/'npu'、page_num/image_dir -> ファイルを predict() に渡します。
3. 3.x に相当するものがないオプションは削除が必要です。詳細な設定は、エクスポートした PaddleX の設定ファイルで編集できます（export_paddlex_config_to_yaml でエクスポートし、paddlex_config=... で指定）。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,155-169; PaddleOCR/paddleocr/_pipelines/base.py:74-100

PPStructureV3 での Unknown argument（layout / table / ocr / structure_version / det_model_dir ...）#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。PPStructureV3(det_model_dir=...)、(use_angle_cls=...)、(use_gpu=...) のいずれも Unknown argument になりました。

ValueError: Unknown argument: table

原因：PPStructureV3 には独自のパラメータ群があり、非推奨名の対応表がありません（det_model_dir や use_angle_cls もここではエラーになります）。

1. table -> use_table_recognition、formula -> use_formula_recognition（現在は既定で True）、image_orientation -> use_doc_orientation_classify、layout_model_dir -> layout_detection_model_dir、table_model_dir -> wired_/wireless_table_structure_recognition_model_dir、det_model_dir -> text_detection_model_dir。
2. layout=False / ocr=False に相当するものはありません。単純な OCR には PaddleOCR を、表には TableRecognitionPipelineV2 を使います。
3. recovery=True -> 各結果で res.save_to_word() / res.save_to_markdown() を呼び出します。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:32-101,129-143

DeprecationWarning: The parameter `use_angle_cls` has been deprecated#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

DeprecationWarning: The parameter `use_angle_cls` has been deprecated and will be removed in the future. Please use `use_textline_orientation` instead.

原因：2.x のパラメータ名も PaddleOCR では引き続き使えますが、警告付きで 3.x の名前に変換されます。

1. 警告に示された名前に変更します（例：use_angle_cls -> use_textline_orientation、det_model_dir -> text_detection_model_dir、rec_batch_num -> text_recognition_batch_size）。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_utils/deprecation.py:36-42; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,156-159

`use_angle_cls` and `use_textline_orientation` are mutually exclusive#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive.

原因：非推奨の名前とその後継の名前を両方指定しています（CLI では -- 付きで同じ文言を表示し、終了ステータス 2 で終了します）。

1. 新しい名前だけを残します。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:163-166,595-600

The option `--use_angle_cls` has been deprecated#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

CLIDeprecationWarning: The option `--use_angle_cls` has been deprecated and will be removed in the future. Please refer to the documentation for more details.

原因：paddleocr ocr で 2.x の旧フラグを使っています。

1. 新しいフラグを使います：--use_textline_orientation、--text_detection_model_dir、--text_recognition_model_dir、--text_det_thresh、--text_det_box_thresh、--text_det_unclip_ratio、--text_det_limit_side_len、--text_det_limit_type、--text_recognition_batch_size、--textline_orientation_model_dir、--textline_orientation_batch_size。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_utils/deprecation.py:26-33; PaddleOCR/paddleocr/_pipelines/ocr.py:567-588

predict() got an unexpected keyword argument 'cls'#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

TypeError: PaddleOCR.predict() got an unexpected keyword argument 'cls'

原因：3.x の ocr() は非推奨のエイリアスで、**kwargs を predict() に転送します。predict() のキーワード専用引数には cls/det/rec/bin/inv/alpha_color/slice がありません（正確な文言は Python が生成します。Python 3.10 未満ではクラス名が省略されます）。

1. ocr.ocr(img, cls=True) -> PaddleOCR(use_textline_orientation=True) で作成したうえで ocr.predict(img)、または predict(img, use_textline_orientation=True)。
2. det=False -> TextRecognition().predict(crops)、rec=False -> TextDetection().predict(img)。
3. bin/inv/alpha_color/slice に相当する predict() の引数はありません。

ocr = PaddleOCR(use_textline_orientation=True)
result = ocr.predict('img.png')

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:208-241; PaddleOCR/docs/update/upgrade_notes.en.md:69; paddleocr-2.10.0/paddleocr/paddleocr.py:696-706

DeprecationWarning: Please use `predict` instead.#

DeprecationWarning: Please use `predict` instead.

原因：3.x では PaddleOCR.ocr() に typing_extensions.deprecated デコレーターが付いています。

1. .ocr(img) を .predict(img) に置き換えます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:239-241; PaddleOCR/paddleocr/_utils/deprecation.py:19

cannot import name 'draw_ocr' from 'paddleocr'#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ImportError: cannot import name 'draw_ocr' from 'paddleocr'

原因：draw_ocr は 2.x でエクスポートされていた関数です。3.x では結果オブジェクト自身が描画します。

1. インポートを削除します。
2. res.save_to_img('output_dir') または res.img['ocr_res_img']（PIL Image）を使います。
3. 独自のフォントを使うには、環境変数 PADDLE_PDX_LOCAL_FONT_FILE_PATH=/path/to/font.ttf を設定します。

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en')
for res in ocr.predict('img.png'):
    res.save_to_img('output')
    img = res.img['ocr_res_img']  # PIL.Image

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; PaddleOCR/docs/update/upgrade_notes.en.md:38-48,65-66; PaddleOCR/docs/FAQ.en.md:195-197

cannot import name 'PPStructure' from 'paddleocr'#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ImportError: cannot import name 'PPStructure' from 'paddleocr'

原因：PPStructure は 3.x で削除されました。

1. pip install "paddleocr[doc-parser]"
2. from paddleocr import PPStructureV3
3. pipeline = PPStructureV3(); output = pipeline.predict('doc.png'); for res in output: res.save_to_markdown('out'); res.save_to_json('out')

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/docs/update/upgrade_notes.en.md:73; PaddleOCR/paddleocr/__init__.py:32-43; PaddleOCR/docs/version3.x/pipeline_usage/PP-StructureV3.en.md:963,1686-1700

cannot import name 'save_structure_res' / 'sorted_layout_boxes' / 'convert_info_docx'#

ImportError: cannot import name 'save_structure_res' from 'paddleocr'

原因：2.x の PP-Structure 用ヘルパー関数は 3.x のパッケージに含まれていません。

1. save_structure_res -> res.save_to_json / save_to_xlsx / save_to_html / save_to_img（または res.save_all）。
2. convert_info_docx -> res.save_to_word(path)。
3. convert_info_markdown / sorted_layout_boxes -> res.save_to_markdown(path)、pipeline.concatenate_markdown_pages(...)。
4. to_excel -> res.save_to_xlsx(path)。
5. download_with_progressbar -> 不要です。モデルは自動でダウンロードされます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:69,216,400,526,590,797

No module named 'paddleocr.tools' / 'paddleocr.ppocr' / 'paddleocr.ppstructure'#

ModuleNotFoundError: No module named 'paddleocr.tools'

原因：2.x の wheel はパッケージ内に tools/、ppocr/、ppstructure/、paddleocr.py を含んでいましたが、3.x のパッケージには、厳選された公開 API を持つ paddleocr/ だけが含まれます。

1. インポートはトップレベルのパッケージからのみ行います：from paddleocr import PaddleOCR, PPStructureV3, TextDetection, ...
2. 2.x の内部モジュールが必要な場合は、別の仮想環境で paddleocr==2.10.0 に固定します。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/pyproject.toml:61-64; PaddleOCR/paddleocr/__init__.py:84-131

2.x のコードで 3.x の結果を読むと KeyError: 0 / string indices#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。result[0][0][1][0] は KeyError: 0 になり、2.x のループ `for line in result[0]: box, (text, score) = line` は辞書のキーを走査して ValueError: too many values to unpack (expected 2) になりました。

KeyError: 0

原因：3.x の predict()/ocr() が返すのは OCRResult オブジェクト（rec_texts、rec_scores、rec_polys などのキーを持つ dict のサブクラス）のリストで、[[box, (text, score)], ...] ではありません。result[0][0] は辞書のキー 0 を参照します（NoneType のバリエーションは 2.x の挙動で、2.x は文字のない画像に対して None を返していました）。

1. 結果を反復し、名前付きのフィールドを読みます：res['rec_texts']、res['rec_scores']、res['rec_polys']（4x2 の int16 配列）、res['rec_boxes']（[x_min, y_min, x_max, y_max]）。
2. JSON に変換できる dict が必要なら res.json を使います（{'res': {...}}）。

for res in ocr.predict('img.png'):
    for text, score, poly in zip(res['rec_texts'], res['rec_scores'], res['rec_polys']):
        print(text, score, poly.tolist())

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/common/result/base_result.py:75; paddlex-3.7.2/paddlex/inference/pipelines/ocr/result.py:31; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:197-207; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1836-1853; paddleocr-2.10.0/paddleocr/paddleocr.py:762-772

Invalid OCR version#

ValueError: Invalid OCR version: PP-OCRv2. Supported values are ['PP-OCRv3', 'PP-OCRv4', 'PP-OCRv5', 'PP-OCRv6'].

原因：2.x は PP-OCR と PP-OCRv2 を受け付けていました。3.x の PaddleOCR が受け付けるのは PP-OCRv3〜PP-OCRv6、PPStructureV3 は PP-OCRv3〜PP-OCRv5 のみです。

1. ocr_version='PP-OCRv5' または 'PP-OCRv6' を使います（省略しても構いません）。
2. PPStructureV3 には 'PP-OCRv6' を渡さないでください。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:58,97-100; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:28,103-106; paddleocr-2.10.0/paddleocr/paddleocr.py:91

paddleocr: error: argument COMMAND: invalid choice#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に再現：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

paddleocr: error: argument COMMAND: invalid choice: 'img.png' (choose from ...)

原因：2.x の CLI 構文（paddleocr --image_dir x --use_angle_cls true）を 3.x の CLI で使っています。3.x の CLI はサブコマンドが必須で、入力は -i/--input で指定します。メッセージは Python の argparse が出力するものです（同じ構成のパーサーを使い、Python 3.13 でローカルに再現）。

1. paddleocr ocr -i img.png --use_textline_orientation True
2. 文書構造解析：paddleocr pp_structurev3 -i doc.pdf --save_path out
3. テキスト検出のみ：paddleocr text_detection -i img.png、文字認識のみ：paddleocr text_recognition -i crop.png
4. GPU/CPU：--device gpu:0 | --device cpu

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_cli.py:281-309; PaddleOCR/paddleocr/_utils/cli.py:31-45; PaddleOCR/paddleocr/_common_args.py:129-188

同じ画像でも 3.x の結果・速度が 2.x と異なる（エラーなし）#

(behaviour change, no error)

原因：既定値が変わりました。既定のモデルは PP-OCRv6_medium（2.x は PP-OCRv4）、OCR パイプラインの YAML では文書の向き補正・UVDoc による歪み補正・テキスト行の向き分類がオン、テキスト検出の limit_side_len は 64/min で max_side_limit 4000（2.x は 960/max）、text_rec_score_thresh は 0.0（2.x の drop_score は 0.5）、enable_mkldnn は True（2.x は False）です。

1. 2.x に近い挙動にするには：PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, text_rec_score_thresh=0.5)。
2. モデルを固定するには、ocr_version='PP-OCRv4'（ch/en のみ）を指定するか、*_model_name を明示します。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-45; PaddleOCR/paddleocr/_pipelines/ocr.py:330-331; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:62-63,107,124,131; paddleocr-2.10.0/paddleocr/paddleocr.py:90; PaddleOCR/paddleocr/_constants.py:18; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1293-1298

インストールと依存関係#

Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.#

RuntimeError: Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.

原因：ランタイムをインストールせずに engine='onnxruntime' / 'transformers' / enable_hpi を選択しています。GPU で ONNX を使うには CUDAExecutionProvider が必要です（onnxruntime エンジンが対応するのは cpu と gpu のみ）。

1. pip install onnxruntime（CPU）または onnxruntime-gpu（NVIDIA、CUDA 12.x）。
2. Transformers エンジン：pip install "transformers>=5.10.0" とそのバックエンド。
3. HPI：paddleocr install_hpi_deps cpu|gpu|npu。
4. 1 つの環境に入れる推論エンジンは 1 つだけにします。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/models/engines/onnxruntime.py:59-82; paddlex-3.7.2/paddlex/inference/models/engines/transformers.py:73-77; paddlex-3.7.2/paddlex/inference/models/engines/hpi.py:66-70; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:32-58; PaddleOCR/paddleocr/_cli.py:96-107

pip で paddlepaddle-gpu 3.x が見つからない（No matching distribution found）#

ERROR: No matching distribution found for paddlepaddle-gpu==3.2.0

原因：PyPI の paddlepaddle-gpu は 2.6.2 で止まっており（pypi.org の JSON で確認）、3.x の GPU 版 wheel は PaddlePaddle 独自のインデックスで配布されています。PyPI から単に pip install paddlepaddle-gpu を実行すると 2.6.2 が入り、PaddleOCR 3.x の要件である PaddlePaddle >= 3.0.0 を満たしません。PyPI の CPU 版 paddlepaddle 3.3.1 の wheel は、CPython 3.9〜3.13 の manylinux x86_64、Windows amd64、macOS arm64 向けのみです。

1. 公式のインデックス URL を使います：python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/（古いドライバーでは cu118）。
2. Python 3.9〜3.13 を使います。
3. wheel は、ローカルの CUDA Toolkit のバージョンではなく GPU ドライバーのバージョンで選びます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：https://pypi.org/pypi/paddlepaddle-gpu/json (latest 2.6.2, fetched 2026-10-27); https://pypi.org/pypi/paddlepaddle/3.3.1/json; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:54-65; PaddleOCR/docs/version3.x/paddleocr_and_paddlex.en.md:27-39

No module named 'pyclipper' / 'shapely' / 'cv2'#

ModuleNotFoundError: No module named 'pyclipper'

原因：pyclipper、shapely、opencv-contrib-python、pypdfium2、python-bidi は、paddleocr が依存する paddlex[ocr-core] から入ります。--no-deps でインストールした場合（リポジトリの FAQ が依存関係の衝突時に勧めている方法）や、手動でアンインストールした場合に欠落します。

1. pip install --force-reinstall "paddleocr"（--no-deps なし）、または pip install "paddlex[ocr-core]>=3.7.0,<3.8.0"。
2. 新しい仮想環境を使います。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2.dist-info/METADATA:101-106; PaddleOCR/pyproject.toml:49-55; PaddleOCR/docs/FAQ.en.md:15-20

NumPy 2／numpy のバージョン衝突#

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.x.x as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.

原因：paddlex 3.7.2 は numpy>=1.24,<2.4 を要求し（paddlepaddle 3.3.1 は numpy>=1.21）、3.x では NumPy 2.0〜2.3 がサポートされています。エラーの原因は、(a) numpy >= 2.4 が環境に強制的に入っている、または (b) NumPy 1.x 向けにコンパイルされた拡張モジュール（古い 2.x 時代の環境など）を NumPy 2 で動かしている、のいずれかです。このメッセージは NumPy 自身が出力します。

1. pip install "numpy>=1.24,<2.4"
2. トレースバックに表示されたパッケージをアップグレードします（古い 2.x の環境を使い続ける場合は numpy を <2 にダウングレード）。
3. paddleocr 2.x から 3.x に移行する際は、新しい環境を作るのが無難です。

対象：paddleocr 3.x の環境、および NumPy 2 に更新した古い paddleocr 2.x の環境。出典：paddlex-3.7.2.dist-info/METADATA:35; https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist); numpy v2.0.0 numpy/core/_multiarray_umath.py:23-29 and numpy/__init__.py:395-399 (raw.githubusercontent.com/numpy/numpy/v2.0.0)

paddle のインポート時に protobuf エラー#

(varies; e.g. 'TypeError: Descriptors cannot be created directly.')

原因：paddlepaddle 3.2.2 と 3.3.1 は protobuf>=3.20.2 を宣言しており、他のパッケージが古い protobuf に固定していると衝突します。

1. pip install --upgrade "protobuf>=3.20.2"
2. PaddleOCR は専用の仮想環境にインストールします。

対象：paddlepaddle 3.x。出典：https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist: protobuf>=3.20.2); https://pypi.org/pypi/paddlepaddle/3.2.2/json

Apple Silicon（M1〜M4）で動くインストール方法#

(no single error string)

原因：paddlepaddle は PyPI で macOS arm64 向けの CPU 版 wheel（cp39〜cp313）を公開しています。公式の PaddleOCR-VL Apple Silicon ガイドは CPU インデックスから paddlepaddle==3.2.1 をインストールし、>= 3.2.1 を要件としています。このハードウェアでは Docker は非対応で、ローカルで使えるエンジンは PaddlePaddle のみです。CUDA はないため device='cpu' を使います。

1. python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
2. python -m pip install -U "paddleocr[doc-parser]"（OCR だけなら paddleocr のみ）
3. device='cpu' で実行します。

対象：Apple Silicon の macOS。出典：PaddleOCR/docs/version3.x/pipeline_usage/PaddleOCR-VL-Apple-Silicon.en.md:31-60; https://pypi.org/pypi/paddlepaddle/3.3.1/json (macosx_11_0_arm64 wheels)

[W:onnxruntime ... Removing initializer ...] の警告#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 にテスト：paddleocr 3.7.0 + onnxruntime 1.31.1、PaddlePaddle はインストールなし。

[W:onnxruntime:...] ... Removing initializer ...

原因：engine='onnxruntime' では、モデルの読み込み時に ONNX Runtime が 'Removing initializer' という警告を大量に出力します。私たちのテストでは無害でした。onnxruntime 1.31.1 だけを入れた（PaddlePaddle なしの）paddleocr 3.7.0 で、正しい結果が返りました。

1. 無視して構いません。初回読み込み時に表示されましたが、出力は変わりませんでした。
2. PaddlePaddle をまったく使わずに動かすには：pip install paddleocr onnxruntime を実行し、PaddleOCR(engine='onnxruntime') を使います。

# pip install paddleocr onnxruntime
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', engine='onnxruntime')

対象：engine='onnxruntime' を使う paddleocr 3.5 以降。出典：paddleocr.dev によるテスト 2026-10-27 (paddleocr 3.7.0, onnxruntime 1.31.1); PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:50-58

CPU・速度・推論エンジン#

Invalid precision / Invalid engine#

ValueError: Invalid precision: int8. Supported values are: ['fp32', 'fp16'].

原因：precision に指定できるのは fp32/fp16 のみ、engine に指定できるのは None、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime のみです。

1. precision='fp16' は use_tensorrt=True と組み合わせて使うか、指定を省略します。
2. engine には上記の値のいずれかを使います。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_common_args.py:29-35,58-69; PaddleOCR/paddleocr/_constants.py:21

MKL-DNN is not available#

ValueError: MKL-DNN is not available

原因：MKL-DNN を持たない Paddle のビルドや CPU で、run_mode 'mkldnn' を明示的に要求しています（例：engine_config={'run_mode': 'mkldnn'}）。関連する警告「The model(X) is not supported to run in MKLDNN mode! Using paddle instead!」は情報提供のためのもので、そのモデルが PaddleX の MKLDNN ブロックリストに含まれていることを示します（例：SLANet、UVDoc、PP-FormulaNet）。

1. run_mode 'paddle' を使うか、run_mode を省略します。enable_mkldnn（既定値 True）の場合、PaddleX は利用可能なときだけ mkldnn を選びます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/pp_option.py:31-43,161-170; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:317-327; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/blocklists.py:46

engine_config cannot mix per-engine bucket keys with flat config keys#

ValueError: engine_config cannot mix per-engine bucket keys with flat config keys. Use either a flat dict for the resolved engine only, or a dict whose top-level keys are exclusively inference engine names. Flat-like keys: [...]; bucket-like keys: [...].

原因：engine_config で {'paddle_static': {...}} のようなエンジン別のキーと、'run_mode' のようなフラットなキーを混在させています。

1. 選択したエンジン用のフラットな dict（engine='paddle_static', engine_config={'run_mode': 'paddle', 'cpu_threads': 4}）を使うか、エンジン名のキーだけを使います。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/models/__init__.py:176-213; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:134-141

CPU で PaddleOCR が遅い#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 に計測（4 vCPU の Intel Xeon @ 2.10 GHz、GPU なし）。

(no error: each page takes several seconds)

原因：3.x の標準 OCR パイプラインは、PP-OCRv6_medium に加えて、既定でオンになっている 3 つの補助モデル（文書の向き補正、UVDoc による歪み補正、テキスト行の向き分類）を実行します。CPU では、PaddlePaddle は oneDNN（既定値の enable_mkldnn=True）経由が最も高速です。私たちのベンチマーク（補助モデルはオフ）では、1 ページあたりの平均が PP-OCRv6_medium で PaddlePaddle 3.2.0 が 4.51 秒、ONNX Runtime が 2.92 秒、PP-OCRv6_small で 1.23 秒／0.90 秒、PP-OCRv6_tiny で 0.39 秒／0.26 秒でした。enable_mkldnn=False（PaddlePaddle 3.3.1）では medium が 11.88 秒かかりました。

1. 正しい向きの平らなスキャン画像なら、補助モデルをオフにします：PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False)。
2. pip install onnxruntime を実行し、engine='onnxruntime' を試します。私たちのテストでは PP-OCRv6 で最速でした。例外として、PP-OCRv5_server は ONNX Runtime で大幅に遅くなりました（1 ページあたり 35.70 秒 vs 5.25 秒）。
3. 小さいモデルを使います：text_detection_model_name='PP-OCRv6_small_det'、text_recognition_model_name='PP-OCRv6_small_rec'（または _tiny の組み合わせ）。
4. 3.3.x のクラッシュを避けるには、oneDNN を無効にするのではなく、enable_mkldnn=True のまま paddlepaddle==3.2.0 に固定します。
5. PaddleOCR オブジェクトは 1 回だけ作成して使い回します。最初の predict() は遅くなります（私たちのテストではレシートで初回 4.88 秒、3 回の中央値は 3.23 秒）。

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    text_detection_model_name='PP-OCRv6_small_det',
    text_recognition_model_name='PP-OCRv6_small_rec',
    engine='onnxruntime',  # pip install onnxruntime
)

対象：CPU 上の paddleocr 3.x。出典：paddleocr.dev ベンチマーク： _src/data/bench/summary.json, results.jsonl (2026-10-27); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13; PaddleOCR/paddleocr/_constants.py:18

GPU#

device='cuda'（その他の無効なデバイス文字列）で AssertionError#

AssertionError (from paddlex/utils/device.py parse_device)

原因：PaddleX が受け付けるデバイスの種類は cpu、gpu、xpu、npu、mlu、gcu、dcu、iluvatar_gpu、metax_gpu です。'cuda'、'cuda:0'、'mps' は単純な assert で拒否され、'cpu:0' は 'No Device ID should be specified for CPUs' になります。

1. device='gpu' または 'gpu:0' を使います（'cuda' ではありません）。
2. device='cpu' を使います（番号なし）。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/utils/device.py:31-41,78-100

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly#

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly. (error code is ...)
  Suggestions:
  1. Check if the third-party dynamic library (e.g. CUDA, CUDNN) is installed correctly and its version is matched with paddlepaddle you installed.
  2. Configure third-party dynamic library environment variables as follows:
  - Linux: set LD_LIBRARY_PATH by `export LD_LIBRARY_PATH=...`

原因：paddlepaddle-gpu が、ビルド時のバージョンに対応する CUDA／cuDNN のライブラリを dlopen できませんでした。

1. ドライバーに合った paddlepaddle-gpu のビルドをインストールします（cu118 にはドライバー >= 450.80.02、cu126 には >= 550.54.14 が必要）。
2. または公式 Docker イメージ paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6 / paddle:3.0.0-gpu-cuda12.6-cudnn9.5-trt10.5 を使います。
3. ライブラリは存在するのに見つからない場合は、そのディレクトリを LD_LIBRARY_PATH（Linux）／PATH（Windows）に追加します。

対象：paddlepaddle-gpu 3.x（paddleocr 3.x 全般）。出典：Paddle v3.3.1 paddle/phi/backends/dynload/dynamic_loader.cc:386-400; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:16-28,58-65

Out of memory error on GPU 0 (ResourceExhaustedError)#

ResourceExhaustedError: 

Out of memory error on GPU 0. Cannot allocate ... memory on GPU 0, ... memory has been allocated(actual using allocated memory ...) and available memory is only ....

Please check whether there is any other process using GPU 0.
1. If yes, please stop them, or start PaddlePaddle on another GPU.
2. If no, please decrease the batch size of your model.

原因：GPU メモリが不足しています（大きな画像、大きなバッチ、サーバー向けの大きなモデル、または GPU 上の他のプロセス）。

1. GPU を空けるか、別の GPU を選びます：device='gpu:1'。
2. バッチサイズを下げます：text_recognition_batch_size=1、textline_orientation_batch_size=1。
3. テキスト検出の解像度を下げます：text_det_limit_side_len / text_det_limit_type、またはエクスポートした設定で max_side_limit を小さくします。
4. mobile モデルを使います。例：text_detection_model_name='PP-OCRv5_mobile_det'、text_recognition_model_name='PP-OCRv5_mobile_rec'。
5. 不要なサブモデルを無効にします（use_doc_orientation_classify=False、use_doc_unwarping=False）。
6. 注意：リポジトリの FAQ には gpu_mem / batch_size / enable_memory_optim / det_limit_side_len も挙げられていますが、3.x ではこれらは PaddleOCR のコンストラクタ引数ではありません（gpu_mem などは 'Unknown argument' になります）。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：Paddle v3.3.1 paddle/phi/core/memory/allocation/cuda_allocator.cc:75-83; PaddleOCR/docs/FAQ.en.md:85-92; PaddleOCR/paddleocr/_pipelines/ocr.py:73-92; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:796

Windows の NVIDIA RTX 50 シリーズ GPU が標準の paddlepaddle-gpu で動かない#

(no single error string documented)

原因：公式ドキュメントによると、標準の方法でインストールした PaddlePaddle は Windows 上の NVIDIA 50 シリーズ GPU を正しくサポートしておらず、専用の CUDA 12.9 版 wheel が提供されています（文字認識モデルの学習には既知の問題が残っています）。

1. paddlepaddle_installation に掲載されている、お使いの Python バージョン用の専用 wheel（paddlepaddle_gpu-3.0.0.dev20250717-cp3XX-cp3XX-win_amd64.whl）をインストールします。

対象：Windows + NVIDIA RTX 50 シリーズ。出典：PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:79-97

モデルと言語#

No models are available for lang=... and ocr_version=...#

ValueError: No models are available for lang='latin' and ocr_version=None.

原因：lang と ocr_version の組み合わせに対応するモデルがありません。移行時によくあるのは、2.x の文字体系グループのコード（'latin'、'arabic'、'cyrillic'、'devanagari'、'ch_doc'、'structure'）が 3.x では lang として受け付けられないケースです。また、PP-OCRv4 は 'ch' と 'en' のみ、PP-OCRv6 は ch/chinese_cht/en/japan とラテン文字の言語のみに対応します。PPStructureV3 では「No models are available for the language 'xx' and OCR version 'yy'.」という文言になります。

1. 実際の言語コードを使います（例：'fr'、'de'、'es'、'ru'、'ar'、'hi'、'korean'、'japan'）。
2. ocr_version を外すと、PaddleOCR がその言語に対応する最新のバージョンを選びます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:58-62,113-119,318-422; PaddleOCR/paddleocr/_utils/langs.py; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:119-125; paddleocr-2.10.0/paddleocr/paddleocr.py:506-527

`lang` and `ocr_version` will be ignored when model names or model directories are not `None`.#

UserWarning: `lang` and `ocr_version` will be ignored when model names or model directories are not `None`.

原因：lang／ocr_version を、text_detection_model_*／text_recognition_model_*（または非推奨の det_model_dir／rec_model_dir）と一緒に指定しています。

1. モデルは lang／ocr_version で選ぶか、モデル名／ディレクトリを明示して選ぶかのどちらか一方にします。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：PaddleOCR/paddleocr/_pipelines/ocr.py:122-127

Model name mismatch: expected 'PP-OCRv6_medium_det' but config has ...#

ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir.

原因：*_model_dir を対応する *_model_name なしで指定したため、パイプラインは既定のモデル名（OCR の YAML では PP-OCRv6_medium_det / PP-OCRv6_medium_rec）のままとなり、PaddleX がそれをディレクトリ内の inference.yml にある Global.model_name と比較しています。

1. ディレクトリに合ったモデル名を指定します。例：text_detection_model_name='PP-OCRv5_server_det'、text_detection_model_dir='./PP-OCRv5_server_det_infer'。
2. 3.x 形式の推論モデルのディレクトリ（inference.yml を含む）を使います。

ocr = PaddleOCR(
    text_detection_model_name='PP-OCRv5_server_det',
    text_detection_model_dir='./models/PP-OCRv5_server_det_infer',
    text_recognition_model_name='PP-OCRv5_server_rec',
    text_recognition_model_dir='./models/PP-OCRv5_server_rec_infer',
)

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/models/utils/model_resolver.py:25-44; paddlex-3.7.2/paddlex/inference/models/utils/model_config.py:24-31; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:27,42; PaddleOCR/paddleocr/_pipelines/utils.py:14-27

No model hoster is available / No available model hosting platforms detected#

Exception: No available model hosting platforms detected. Please check your network connection.

原因：PaddleX は初回使用時に、接続確認を行ったうえで HuggingFace（既定）、AIStudio、ModelScope、BOS のいずれかから公式モデルをダウンロードします。ファイアウォールやプロキシ、オフラインのホストでは、すべての取得元が失敗します。

1. paddleocr をインポートする前に、優先する取得元を設定します：os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos'（値は huggingface、modelscope、aistudio、bos。大文字・小文字は区別しません）。
2. 時間のかかる接続確認を省略します：PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK=True。
3. 独自の HF ミラー：PADDLE_PDX_HUGGING_FACE_ENDPOINT=https://...
4. オフライン：モデルを ~/.paddlex/official_models/<model_name> にコピーする（キャッシュのルートは PADDLE_PDX_CACHE_HOME）か、*_model_dir を対応する *_model_name と一緒に指定します。

import os
os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos'
os.environ['PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK'] = 'True'
from paddleocr import PaddleOCR

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/utils/official_models.py:878-921,962-967,1015-1041; paddlex-3.7.2/paddlex/utils/flags.py:72-79; paddlex-3.7.2/paddlex/utils/cache.py:28-29; PaddleOCR/docs/FAQ.en.md:29-34,55-60

No valid model files were found for engine 'paddle_static' / No valid PaddlePaddle model found#

ValueError: No valid model files were found for engine 'paddle_static'.

原因：モデルのディレクトリに、inference.json または inference.pdmodel と inference.pdiparams の組（あるいは選択したエンジンが必要とする形式。onnxruntime なら inference.onnx など）がありません。

1. *_model_dir には、エクスポート済みの推論モデルのフォルダー（inference.json/.pdmodel + inference.pdiparams + inference.yml）を指定します。
2. ~/.paddlex/official_models/ 以下のダウンロード途中のフォルダーを削除し、再ダウンロードさせます。

対象：paddleocr 3.x（リポジトリのコミット dab3fe3／paddleocr 3.7.x + paddlex 3.7.2 で確認）。出典：paddlex-3.7.2/paddlex/inference/models/engines/_base.py:107-115; paddlex-3.7.2/paddlex/inference/models/utils/model_paths.py:50-76; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:345-347; paddlex-3.7.2/paddlex/inference/utils/official_models.py:944-946

結果#

結果が空：rec_texts が []#

{'rec_texts': [], 'rec_scores': [], ...}   (2.x returned [None])

原因：3.x が None を返すことはありません。採用された文字がない画像では、rec_texts、rec_scores、rec_polys が空のリストの OCRResult が返ります（2.x は代わりに None を追加していました）。文字が失われる箇所は、テキスト検出（既定値は text_det_thresh 0.3、text_det_box_thresh 0.6）か、スコアによるフィルタ text_rec_score_thresh です。rec_* にはスコアがこの値以上の行だけが残り、dt_polys には検出されたすべての枠が残ります。

1. res['dt_polys'] を出力します。空ならテキスト検出が何も見つけていません。枠があるのに rec_texts が空なら、スコアのフィルタですべて除外されています。
2. テキスト検出：薄い文字やコントラストの低い文字には、text_det_box_thresh（例：0.4）や text_det_thresh を下げます。
3. スコアのフィルタ：3.x の既定値は 0.0 です。2.x の drop_score（0.5）から引き継いだ値があると、信頼度の低い行が表示されません。
4. lang を文書の言語に設定します。既定の PP-OCRv6 モデルは中国語、英語、日本語、ラテン文字の言語に対応しています。
5. if result[0] is None のような 2.x のチェックは、if not result[0]['rec_texts'] に置き換えます。

res = ocr.predict('page.png')[0]
print(len(res['dt_polys']), 'boxes detected')
print(res['rec_texts'])
# faint text:
res = ocr.predict('page.png', text_det_box_thresh=0.4, text_rec_score_thresh=0.0)[0]

対象：paddleocr 3.x。出典：paddleocr-2.10.0/paddleocr/paddleocr.py:762-772; paddlex-3.7.2/paddlex/inference/pipelines/ocr/pipeline.py:480-498; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:32-45; PaddleOCR/paddleocr/_pipelines/ocr.py:58-62

検出枠が元の画像と合わない#

paddleocr.dev で再現済み paddleocr.dev が 2026-10-27 にテスト：paddleocr 3.7.0 + paddlepaddle 3.2.0。

(no error: rec_polys / rec_boxes look shifted when drawn on your own copy of the image)

原因：既定の PaddleOCR() は use_doc_unwarping=True です。UVDoc が先にページの歪みを補正し、検出枠は元の画像ではなく、その処理後の画像の座標で返されます。私たちのレシートでは、最初の行が歪み補正ありで [[119,11],[507,8],[507,46],[120,49]]、なしで [[128,55],[489,55],[489,82],[128,82]] でした。文書の向き補正（これも既定でオン）によってページが回転することもあります。

1. 元の画像上の座標が必要なら：PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False)。
2. または PaddleOCR 自身が描画した画像を使います：res.save_to_img('out') は ocr_res_img と preprocessed_img の両方を書き出します（res.img にも同じ 2 つのキーがあります）。

ocr = PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False)
res = ocr.predict('receipt.png')[0]
print(res['rec_polys'][0])

対象：既定設定の paddleocr 3.x OCR パイプライン。出典：paddleocr.dev によるテスト 2026-10-27 (paddleocr 3.7.0 + paddlepaddle 3.2.0); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13

よくある質問#