PaddleOCR 2.x のコードを 3.x に移行する

2.x → 3.x コード変換ツール#

変換ツールは推測ではなく、ルールに基づいて動作します。理解できるパターンだけを書き換え、変更ごとに根拠となる PaddleOCR のソース行を示し、人の判断が必要な箇所には # TODO(paddleocr 3.x) コメントを残します。最初の 2 つのサンプルの出力を PaddleOCR 3.7.0 で実行したところ、どちらもエラーなく動作してテスト用レシートの 27 行すべてを読み取り、1 つ目は result.jpg を書き出しました。なお、ツールが表示する変更点の説明は英語です。⁷

3.x で何が変わったのか、そしてその理由#

PaddleOCR 2.x は 2021 年から 2025 年初めにかけて、1 つの軽量なコードベースに機能を追加する形で成長しました。メンテナーのアップグレードノートによると、その方法は限界に達していました。コードの重複、一貫性のないインターフェース、新しい PaddlePaddle では動かなくなった古い依存関係です。その答えが「後方互換性のない大規模なアップグレード」でした。² 3.x の paddleocr パッケージは PaddleX のパイプラインを包む薄いラッパーで、PaddleOCR は PaddleX の OCR パイプラインをラップして結果オブジェクトを返します。¹

1. 2023年9月15日paddleocr 2.7.0.3 — 古い requirements.txt で今もよく固定されているバージョン。
2. 2025年3月7日paddleocr 2.10.0 — 最後の 2.x リリース。
3. 2025年5月20日paddleocr 3.0.0 — PaddleX ベースの新しい API。
4. 2026年6月11日paddleocr 3.7.0 — 現行リリース。既定で PP-OCRv6 モデルを使用。

日付は PyPI への最初のアップロード日です。⁶ 現在バージョンを指定せずに paddleocr をインストールすると 3.7.0 が入るため、新しい環境を作った時点で 2.x のコードは動かなくなります。原因となる変更は次のとおりです。

このほか、エラーにはならないものの出力が変わる変更が 2 つあります。新しい既定のモデルと前処理（黙って変わった既定値で解説）、そして推論エンジンのインストールです。3.x の pip install paddleocr では PaddlePaddle はインストールされず、PyPI の paddlepaddle-gpu パッケージは 2.6.2 で止まっています。インストールガイドを参照してください。

use_angle_cls と、今も使える 11 個の旧名#

3.x には、PaddleOCR の旧キーワード引数を変換する小さな対応表があります。ソースからそのまま引用した完全な一覧です。¹

_DEPRECATED_PARAM_NAME_MAPPING = {
    "det_model_dir": "text_detection_model_dir",
    "det_limit_side_len": "text_det_limit_side_len",
    "det_limit_type": "text_det_limit_type",
    "det_db_thresh": "text_det_thresh",
    "det_db_box_thresh": "text_det_box_thresh",
    "det_db_unclip_ratio": "text_det_unclip_ratio",
    "rec_model_dir": "text_recognition_model_dir",
    "rec_batch_num": "text_recognition_batch_size",
    "use_angle_cls": "use_textline_orientation",
    "cls_model_dir": "textline_orientation_model_dir",
    "cls_batch_num": "textline_orientation_batch_size",
}

これらを渡すと、3.x が警告付きで名前を変換します。3.7.0 で PaddleOCR(lang='en', use_angle_cls=True) を実行すると、次のとおり出力されました。⁷

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

Python は __main__ から発生したもの以外の DeprecationWarning を既定で表示しないため、この警告に気づかない人も多くいます。この対応表の周辺のコードから、次の 3 つのルールがわかります。¹

• 旧名と新名の併用はエラー。PaddleOCR(use_angle_cls=True, use_textline_orientation=True) は ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive. になります（再現済み）。
• 対応表があるのは PaddleOCR だけ。PPStructureV3(det_model_dir=...) と PPStructureV3(use_angle_cls=True) は ValueError: Unknown argument: det_model_dir / use_angle_cls になります。どちらも再現済みです。
• 「使える」は「同じ挙動」ではない。2.x の use_angle_cls の既定値は False でした。3.x で use_textline_orientation を指定しないとパイプラインの既定値が使われ、それは True です。⁵

同じ 11 個は paddleocr ocr の CLI フラグとしても存在します。--use_angle_cls は引き続き動作し、CLIDeprecationWarning: The option `--use_angle_cls` has been deprecated and will be removed in the future. Please refer to the documentation for more details. と表示されます。

use_gpu、show_log、use_onnx、drop_score は警告ではなくエラー#

それ以外の残ったキーワード引数はすべて、3.x のエンジンオプションだけを受け付ける次のループに引っかかります。¹

unknown_names = kwargs.keys() - default_vals.keys()
for name in unknown_names:
    raise ValueError(f"Unknown argument: {name}")

最初に見つけた名前でエラーを送出し、しかも unknown_names は集合なので、古い引数が 3 つあるコンストラクタでも 1 回の実行で報告されるのは 1 つだけです。下の表か変換ツールを使って、まとめて修正してください。3.7.0 での再現結果です。⁷

use_gpu=True      -> ValueError: Unknown argument: use_gpu
show_log=False    -> ValueError: Unknown argument: show_log
use_onnx=True     -> ValueError: Unknown argument: use_onnx
drop_score=0.5    -> ValueError: Unknown argument: drop_score

逆方向のよくある間違いが device='cuda' です。PaddleX はこれを単純な AssertionError で拒否します。GPU のデバイス種別名は gpu です。

ocr(img, cls=True) と新しい結果の形式#

3.x にも ocr() メソッドはありますが、キーワード引数を predict() に転送するだけの非推奨エイリアスです。¹

@deprecated("Please use `predict` instead.")
def ocr(self, img, **kwargs):
    return self.predict(img, **kwargs)

predict() には cls パラメータがないため、2.x のほぼすべてのチュートリアルにある行が失敗します。3.7.0 では次のようになりました。⁷

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

テキスト行の向き分類は、オブジェクトの作成時（use_textline_orientation=True）か、呼び出しごとに predict(img, use_textline_orientation=False) で指定するようになりました。PaddleX のソースから読み取れる注意点が 1 つあります。呼び出しごとにオフにすることはできますが、オフで作成したオブジェクトで呼び出し時にオンにしようとすると、処理は実行されずエラーがログに出力されます。

より大きな変化は戻り値です。2.x の ocr() は画像ごとにリストを返し、各行が [box, (text, score)]、文字が見つからなければ None でした。³ 3.x の predict() は、画像または PDF のページごとに OCRResult を 1 つ返します。これは並列リストを持つ dict です。⁵

このオブジェクトに対して古いループがどう動くかを知っておく価値があります。エラーメッセージに PaddleOCR がまったく出てこないからです。for line in result[0] は dict のキーを走査するため、最初の line は文字列 'input_path' になり、box, (text, score) = line は ValueError: too many values to unpack (expected 2) になります。result[0][0][1][0] のようなインデックス参照は KeyError: 0 になります。どちらも再現済みです。⁷

result = ocr.ocr(img_path, cls=True)
for line in result[0]:
    box, (text, score) = line
    print(text, score, box)

result = ocr.predict(img_path)
for res in result:  # one OCRResult per image / PDF page
    for box, text, score in zip(res['rec_polys'], res['rec_texts'], res['rec_scores']):
        print(text, score, box.tolist())

変換後につまずきやすい点が 3 つあります。ポリゴンは NumPy 配列なので、json.dumps の前に .tolist() を呼ぶ（または res.json を使う）必要があります。文字のないページでは None ではなく空のリストが返るため、if result[0] is None は決して成立しません。if not res['rec_texts'] で判定してください。そして既定の use_doc_unwarping=True では、座標は歪み補正後の画像を基準にします。私たちのレシートでは、最初の行が歪み補正ありで [[119,11],[507,8],[507,46],[120,49]]、なしで [[128,55],[489,55],[489,82],[128,82]] でした。⁷ 詳しくは検出枠が合わないを参照してください。

ocr(img, det=False) と ocr(img, rec=False) に相当するパイプラインの機能はありません。単体モデルのクラスを使います。TextRecognition(model_name="PP-OCRv6_medium_rec").predict(crop) は rec_text と rec_score を、TextDetection(model_name="PP-OCRv6_medium_det").predict(img) は dt_polys と dt_scores を返します。切り出し画像をどう作っているかを推測せずに済むよう、変換ツールはこれらの呼び出しに TODO を付けます。

cannot import name 'draw_ocr' from 'paddleocr'#

draw_ocr は paddleocr 2.10.0 ではエクスポートされていましたが、3.x のパッケージにはないため、インポートが失敗します。⁷

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

現在は結果オブジェクト自身が描画します。アップグレードノートでは、可視化のブロック全体を 1 回の呼び出しに置き換えています。²

from PIL import Image
from paddleocr import draw_ocr
result = result[0]
image = Image.open(img_path).convert('RGB')
boxes = [line[0] for line in result]
txts = [line[1][0] for line in result]
scores = [line[1][1] for line in result]
im_show = draw_ocr(image, boxes, txts, scores, font_path='simfang.ttf')
im_show = Image.fromarray(im_show)
im_show.save('result.jpg')

for res in result:
    res.save_to_img('output')            # writes <name>_ocr_res_img.png (+ preprocessed image)
    pil_image = res.img['ocr_res_img']   # or keep it in memory as a PIL image

私たちのレシートでは、save_to_img('output') が receipt_ocr_res_img.png と receipt_preprocessed_img.png を書き出し、res.img にも同じ 2 つのキーがありました。⁷ 独自のフォントを使うには、font_path を渡す代わりに環境変数 PADDLE_PDX_LOCAL_FONT_FILE_PATH を設定します。削除されたほかのヘルパーも同様に対応します。save_structure_res → res.save_to_json()、save_to_xlsx()、save_to_html()、save_all()、convert_info_docx → res.save_to_word()、to_excel → res.save_to_xlsx()。⁵

det_model_dir と rec_model_dir：独自モデル#

det_model_dir、rec_model_dir、cls_model_dir は 11 個のエイリアスに含まれるため、PaddleOCR では引き続き使えます。ただし内部では次の点が変わります。

• モデル名も指定する。text_detection_model_dir だけを指定すると、パイプラインは既定の名前（PP-OCRv6_medium_det）のままとなり、PaddleX がそれをフォルダー内の inference.yml の名前と比較します。結果は ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir. です。⁵
• フォルダーは 3.x 形式のエクスポートが必要。3.x は inference.json または inference.pdmodel に加え、inference.pdiparams と inference.yml を探します。有効なファイルがないフォルダーでは No valid model files were found for engine 'paddle_static' になります。
• 学習時のオプションは廃止。rec_char_dict_path、rec_algorithm、det_algorithm、use_space_char、max_text_length は Unknown argument になります。モデルは名前で選び、モジュールごとの設定はエクスポートした PaddleX の設定ファイルで行います（export_paddlex_config_to_yaml でエクスポートし、paddlex_config=... で指定）。

from paddleocr import PaddleOCR

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',
)

モデル名やフォルダーを指定すると、lang と ocr_version は UserWarning とともに無視されます。また、2.x の文字体系グループの値 lang='latin'、'arabic'、'cyrillic'、'devanagari' は 3.x では言語コードではなく、No models are available for lang='latin' and ocr_version=None. になります。言語一覧 から実際のコードを選んでください。

黙って変わった既定値#

移行後に動くようになったコードでも、既定値が変わったため、テキスト・検出枠・速度が異なる場合があります。⁵³

変換ツールの「2.x の挙動を維持する」オプションは、エラーデータベースが 2.x に近い出力のために推奨する 4 つのスイッチを追加します：use_doc_orientation_classify=False、use_doc_unwarping=False、use_textline_orientation=False、text_rec_score_thresh=0.5。前処理モデルをオフにすると 3.x の処理も速くなります。モデルは新しいものを使い続けます。新モデルは 5 つのテスト文書で 124 項目中 123 項目を完全に読み取りました（ベンチマーク (EN)）。

PPStructure → PPStructureV3#

3.x では from paddleocr import PPStructure が ImportError: cannot import name 'PPStructure' from 'paddleocr' で失敗します。アップグレードノートが案内する移行先は PPStructureV3 で、追加のインストールが必要です。²⁸

これがないと、PPStructureV3() は RuntimeError: A dependency error occurred during pipeline creation で失敗します（解決策）。コンストラクタには独自のパラメータがあり、エイリアスの対応表はありません。そのため PaddleOCR で使える名前でもここではエラーになります。3.7.0 の PPStructureV3 では、use_gpu、det_model_dir、use_angle_cls、show_log で Unknown argument になりました。⁷

from paddleocr import PPStructure, save_structure_res

table_engine = PPStructure(show_log=True, image_orientation=True, use_gpu=True)
img = cv2.imread(img_path)
result = table_engine(img)
save_structure_res(result, './output', os.path.basename(img_path).split('.')[0])
for line in result:
    line.pop('img')
    print(line)

from paddleocr import PPStructureV3

pipeline = PPStructureV3(use_doc_orientation_classify=True, device='gpu')
output = pipeline.predict(img_path)       # one result per page; PDFs work directly
for res in output:
    res.print()
    res.save_to_json('output')
    res.save_to_markdown('output')        # also: save_to_word, save_to_html, save_to_xlsx, save_to_img

2.x の構造解析の結果は 1 画像分の領域 dict のリストでしたが、3.x の結果はページごとに 1 つのオブジェクトです。出力の詳細や既定で使われる OCR モデルについては、PP-StructureV3 ガイド で解説しています。

コマンドライン：paddleocr --image_dir → paddleocr ocr -i#

3.x の CLI はサブコマンドが必須で、入力は -i で指定します。2.x の書き方は分かりにくい形で失敗します。argparse がファイル名をサブコマンドとして解釈するためです。3.7.0 での実行結果です。⁷

usage: paddleocr [-h] [-v] COMMAND ...
paddleocr: error: argument COMMAND: invalid choice: 'receipt.png' (choose from 'doc_preprocessor', 'doc_understanding', 'formula_recognition_pipeline', 'ocr', 'doc_parser', 'pp_chatocrv4_doc', 'pp_doctranslation', 'pp_structurev3', ...)

真偽値のフラグは true/True/1 を受け付け、それ以外は false として扱われます。私たちのレシートで --save_path を付けて paddleocr ocr を実行したところ、結果を表示し、JSON と 2 つの画像を書き出しました。シェルスクリプト全体を変換ツールに貼り付けることもできます。paddleocr と pip install の行だけを書き換え、それ以外はそのまま残します。

2.x → 3.x の完全な対応表#

変換ツールと同じデータから生成した、検証済みの対応表全 123 項目です。「エイリアス（警告）」は旧名が引き続き使えること、「名称変更」は変更が必要なこと、「置き換え」と「削除」は残しておくとエラーになることを意味します。すべての行に、私たちが確認したファイルと行へのリンクがあります。「変更内容」列の説明は英語のままです。¹³⁵

インポート 13#

PaddleOCR のコンストラクタ引数 47#

PPStructure → PPStructureV3 の引数 18#

メソッドと結果の形式 12#

ヘルパー関数 9#

コマンドライン 24#

2.x を使い続ける：paddleocr を 3 未満に固定#

まだ移行できない場合は、専用の仮想環境で最後の 2.x リリースに固定してください。

これで 2.10.0 が入ります。3.x と同様に、この wheel も PaddlePaddle を依存関係に含まないため、フレームワークは自分でインストールします。³ どの PaddlePaddle 3.x のバージョンで paddleocr 2.x が動くかは検証していないため、動作している 2.x の環境がすでにあるなら、作り直すのではなく固定（pip freeze > requirements.txt）してください。2.x の内部モジュール（paddleocr.tools、paddleocr.ppocr、paddleocr.ppstructure）をインポートするコードは 2.x でしか動きません。これらのモジュールは 3.x のパッケージにはありません。

移行を先延ばしにするほどコストは増えます。2.x には新しいモデルが追加されない一方で、3.x は PP-OCRv5 から PP-OCRv6 に移行し、PaddleOCR-VL も追加されました。

移行チェックリスト#

1. 新しい環境と新しいエンジン#

   新しい venv を作成します。pip install paddleocr を実行し、次に PaddlePaddle のインデックスから paddlepaddle==3.2.0、または onnxruntime をインストールします。インストールコマンド生成ツールで、お使いのマシン用の正確なコマンドがわかります。

2. コードを変換する#

   各ファイルを変換ツールにかけ、すべての # TODO(paddleocr 3.x) を解決します。

3. 一度だけ警告をエラーにする#

   python -W error::DeprecationWarning でテストを実行し、残っているエイリアスや ocr() の呼び出しを洗い出します。

4. 出力を比較する#

   実際の文書をいくつか使ってテキストの差分を取ります。違いがあれば、モデルを疑う前に「2.x の挙動を維持する」スイッチを試してください。

5. 遭遇したエラーを確認する#

   予期しないエラーはエラー解決ツールに貼り付けてください。

よくある質問#