概要：PaddleOCR とは何か、どのパイプラインを使うか

PaddleOCR は、Baidu の PaddlePaddle チームによるオープンソースの OCR / ドキュメント解析ツールキットで、Apache License 2.0 で公開されています。このページは、現行の 3.7 API の実践ガイドです。掲載しているコードはすべて 3.x API に基づいて書かれており、インストール・API・CLI に関する事実は、下記の日付時点で本家ドキュメントと公開済みパッケージで確認しています。

必要な出力に応じてパイプラインを選びます。

独立サイトです。paddleocr.dev は Baidu や PaddleOCR のメンテナーが運営するサイトではありません。信頼できる一次情報としては、GitHub リポジトリと本家ドキュメントをご利用ください。最終確認：2026年10月、PaddleOCR 3.7.0 に対して実施。編集方針（英語）もご覧ください。

インストール

PaddleOCR には推論エンジン（PaddlePaddle）と paddleocr パッケージの両方が必要です。先にエンジンを、次に PaddleOCR をインストールします。仮想環境の使用をおすすめします。

動作要件

• Python 3.9〜3.13（実質的な要件）。paddleocr パッケージ自体は >=3.8 を宣言していますが、PaddlePaddle 3.x のホイールは 3.9〜3.13 向けで、ドキュメント解析には 3.9 以上が必要です。
• OS：Linux、Windows、macOS（Apple Silicon では CPU で動作）。
• NVIDIA GPU（任意）：インストールする CUDA ビルドに対応したドライバー（以下は CUDA 12.6。CUDA 11.8 版も公開されています）。

CPU

python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
        python -m pip install "paddleocr[all]"

NVIDIA GPU（CUDA 12.6）

python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
        python -m pip install "paddleocr[all]"

PyPI から pip install paddlepaddle-gpu を実行しないでください。PyPI にある最新の GPU 版は 2.6.2 で、PaddleOCR 3.x では動作しません。必ず上の -i インデックスを使ってください。対応する CUDA のインデックス（例：cu118）は、PaddlePaddle のインストールセレクターで選べます。

追加パッケージ（extras）

動作確認

import paddle
        paddle.utils.run_check()

        from paddleocr import PaddleOCR
        print("PaddleOCR import OK")

最初の実行時にはモデルの重みをダウンロードする（既定では Hugging Face から）ため、一度だけネットワーク接続が必要です。ダウンロード済みのモデルを使うには、text_detection_model_dir と text_recognition_model_dir を指定します。

クイックスタート：5 行で最初の OCR

PaddleOCR 3.x は結果オブジェクトを返します。predict() を呼び、rec_texts、rec_scores、rec_boxes などのフィールドを読み取ります。

from paddleocr import PaddleOCR

        ocr = PaddleOCR(lang="en")            # "en" の既定モデルは PP-OCRv6（medium）
        result = ocr.predict("invoice.jpg")  # パス、URL、numpy 配列、PDF を指定可能

        for res in result:
            for text, score, box in zip(res["rec_texts"], res["rec_scores"], res["rec_boxes"]):
                if score >= 0.8:
                    print(f"{score:.2f}  {box.tolist()}  {text}")

            res.save_to_img("output")        # 注釈付き画像
            res.save_to_json("output")       # 構造化された結果

コマンドライン

paddleocr ocr -i invoice.jpg --lang en --save_path ./output

結果のフィールド

オプションを視覚的に試したい場合は、ホームページのコードジェネレーターが、環境に合った実行可能なスニペットと CLI コマンドを出力します。

PaddleOCR 2.x からの移行

PaddleOCR 3.x には後方互換性がありません。古いチュートリアル（や古い AI 生成の回答）の多くは、今も 2.x の API を示しています。コードが壊れる主な変更点は次のとおりです。

# 2.x
        # ocr = PaddleOCR(use_angle_cls=True, lang="en", use_gpu=True)
        # result = ocr.ocr("img.jpg", cls=True)

        # 3.x
        from paddleocr import PaddleOCR
        ocr = PaddleOCR(lang="en", device="gpu", use_textline_orientation=True)
        result = ocr.predict("img.jpg")
        for res in result:
            print(res["rec_texts"])

PP-OCRv6：テキスト検出と認識

PP-OCRv6 は PaddleOCR 3.7.0（2026年6月11日）で登場し、PaddleOCR クラスの既定モデルです。以下の数値は Baidu 自身の報告であり、当サイトで独自にベンチマークしたものではありません。

• 言語：1 つの認識モデルが 50 言語（中国語、英語、日本語、ラテン文字の 46 言語）をカバーします。それ以外の文字体系（韓国語、アラビア語、ロシア語、タイ語、ギリシャ語など）は PP-OCRv5 の多言語モデルを使い、lang="korean" は korean_PP-OCRv5_mobile_rec を読み込みます。
• 報告されている向上：medium ティアは PP-OCRv5_server に比べて検出が 4.6%、認識が 5.1% 向上しています。Baidu は、OpenVINO でエンドツーエンドの CPU 速度が 5.2 倍（tiny では Apple M4 上で 6.1 倍）になると報告しています。

ティアを選ぶ

from paddleocr import PaddleOCR

        # 既定（medium）
        ocr = PaddleOCR(lang="en")

        # small / tiny：モデル名を 2 つとも指定
        ocr_small = PaddleOCR(
            text_detection_model_name="PP-OCRv6_small_det",
            text_recognition_model_name="PP-OCRv6_small_rec",
        )

        # 前の世代にとどまる
        ocr_v5 = PaddleOCR(lang="en", ocr_version="PP-OCRv5")

PP-OCRv5 と PP-OCRv6 の違い

ocr_version には "PP-OCRv6"、"PP-OCRv5"、"PP-OCRv4"、"PP-OCRv3" を指定できますが、すべてのバージョンにすべての言語があるわけではありません。指定したバージョンに lang が存在しない場合は、別のバージョンを選ぶか、モデル名を明示的に渡してください。アップグレードしても出力を再現したい場合は、ocr_version を固定します。

主なパラメータ

langstr例："en"

認識する言語。言語コードを参照してください。

ocr_versionstrPP-OCRv6

モデルの世代：PP-OCRv6 / v5 / v4 / v3。

devicestrauto

"cpu"、"gpu"、"gpu:0"、"npu:0"、"xpu:0"、"mlu:0"。

use_doc_orientation_classifyboolTrue

ページ全体の回転（0/90/180/270°）を補正します。きれいで正立した入力なら、オフにして時間を節約できます。

use_doc_unwarpingboolTrue

湾曲したページや撮影したページを平坦化します。スキャンやスクリーンショットではオフにします。

use_textline_orientationboolTrue

上下逆さまの個々の行を補正します。

text_det_threshfloat0.3

検出確率マップに対するピクセルのしきい値。下げると薄い文字を拾いやすくなりますが、ノイズも増えます。

text_det_box_threshfloat0.6

領域をテキストボックスとして残すために必要な平均スコア。

text_det_unclip_ratiofloat2.0

検出領域をどれだけ拡張するか。大きいほどボックスがゆったりします。

text_rec_score_threshfloat0.0

この信頼度を下回る認識結果の行を除外します。

return_word_boxboolFalse

単語単位のボックスも返します。

text_recognition_batch_sizeint1

1 回のバッチで認識する行数。GPU では大きくします。

既定値は、本家の OCR パイプラインのリファレンスに基づいています。既定値やティア名は変わっていくため、お使いのバージョンについてはパイプラインのページを確認してください。

PP-StructureV3：文書を Markdown と JSON に

PP-StructureV3 は、レイアウト検出、OCR、表認識、数式認識、印鑑認識、読み順の復元を組み合わせたパイプラインです。PDF やページ画像を、フラットなテキスト行のリストではなく Markdown や JSON にしたいときに最適です。CPU でも動作しますが、GPU のほうがはるかに高速です。

from paddleocr import PPStructureV3

        pipeline = PPStructureV3(lang="en")   # 使える場合は device="gpu" を追加
        output = pipeline.predict("report.pdf")

        for res in output:
            res.print()
            res.save_to_json(save_path="output")
            res.save_to_markdown(save_path="output")

paddleocr pp_structurev3 -i report.pdf --device cpu --save_path ./output

先に extras をインストールしてください：python -m pip install "paddleocr[doc-parser]"。コンストラクタと CLI の便利なスイッチには、use_doc_orientation_classify、use_doc_unwarping、use_textline_orientationのほか、表・数式・印鑑・チャートごとのモジュール切り替えがあります。速度のため、不要なものは無効にしてください。

実践のヒント

• PDF を自分でラスタライズする場合は、150〜200 DPI 程度にしてください。DPI が極端に高いと、精度はほとんど上がらないまま全体が遅くなります。
• 複数ページの PDF は、ページごとに 1 つの結果を返します。Markdown は自分で連結するか、お使いのバージョンにページ結合のヘルパーがあればそれを使ってください。
• 表は必ず目視で確認してください。セルの結合や罫線のない表は、どの表認識モデルでも間違えやすい箇所です。

PaddleOCR-VL：視覚言語モデルによる文書解析

PaddleOCR-VL は、文書解析（テキスト、表、数式、チャート）向けのコンパクトな視覚言語モデルで、多言語に対応しています。PaddleOCR-VL-1.6 は PaddleOCR 3.6.0（2026年5月28日）で登場し、Baidu は OmniDocBench v1.6 で 96.33% と報告しています（自己報告値）。ここで扱う中では最も精度が高い選択肢ですが、高性能な GPU か専用の推論サーバーが必要です。CPU でも動きますが、本家ドキュメントは本番環境での利用を推奨していません。

python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
        python -m pip install -U "paddleocr[doc-parser]"

from paddleocr import PaddleOCRVL

        pipeline = PaddleOCRVL()                     # 低速な試用なら PaddleOCRVL(device="cpu")
        output = pipeline.predict("page.png")

        for res in output:
            res.print()
            res.save_to_json(save_path="output")
            res.save_to_markdown(save_path="output")

paddleocr doc_parser -i page.png --save_path ./output

複数ページの文書

from paddleocr import PaddleOCRVL

        pipeline = PaddleOCRVL()
        pages = list(pipeline.predict("contract.pdf"))
        merged = pipeline.restructure_pages(pages, merge_tables=True, relevel_titles=True, concatenate_pages=True)

        for res in merged:
            res.save_to_markdown(save_path="output")

推論エンジン

PaddleOCRVL(engine="transformers") は、Paddle エンジンの代わりに Hugging Face Transformers 経由でモデルを実行します。スループットが必要な場合、ドキュメントでは VLM を専用の推論サーバー（vLLM や SGLang など）の背後で動かし、vl_rec_backend で PaddleOCR-VL をそこに向ける方法が説明されています。正確な設定は、お使いのバージョンに対応した PaddleOCR-VL の本家ページに従ってください。

HPD-Parsing：高スループットの解析

HPD-Parsing は、GPU での大規模なバッチ処理を想定した高スループットの文書解析モデルとして、2026年7月22日に PaddleOCR チームから発表されました。他のパイプラインに比べて新しく、情報も少ないため、ここではスループットの数値をあえて繰り返しません。容量計画を立てる前に、リリースノートと本家ドキュメントで、モデルのダウンロード方法、対応ハードウェア、ベンチマークの方法論を確認し、自分の文書でベンチマークしてください。

パフォーマンスチューニング

まず計測しましょう。効果の大きい順に、たいてい効くのは次のポイントです。

1. 不要なモジュールをオフにする。きれいなスキャンなら：use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False。
2. より小さいティアを選ぶ（small または tiny）。手持ちの文書で精度がすでに十分な場合です。
3. オブジェクトを再利用する。PaddleOCR(...) は一度だけ作成します。1 回の呼び出しでは、モデルの読み込みが大半を占めます。
4. GPU ではバッチサイズを上げる（text_recognition_batch_size）。
5. 大きな入力は縮小する。text_det_limit_side_len を下げるか、巨大な写真は OCR の前に縮小します。
6. CPU：enable_mkldnn を有効のままにして cpu_threads を調整します。Intel CPU では OpenVINO エンジンも検討してください。
7. 高性能推論：enable_hpi=True で最適化されたバックエンドが自動的に選ばれます。現時点では Linux x86-64 上の Python 3.8〜3.12 に対応し、追加プラグインが必要です。本家のガイドを参照してください。

from paddleocr import PaddleOCR

        ocr = PaddleOCR(
            lang="en",
            device="gpu",
            use_doc_orientation_classify=False,
            use_doc_unwarping=False,
            use_textline_orientation=False,
            text_recognition_batch_size=16,
        )

GPU とその他のアクセラレーター

device を設定します。NVIDIA なら "gpu" / "gpu:0"、対応する中国系アクセラレーターでは "npu:0"、"xpu:0"、"mlu:0" など（対応する PaddlePaddle ビルドが必要）です。macOS では CPU を使います。GPU が使われている場合、paddle.device.get_device() は gpu:0 と表示するはずで、cpu と表示されるなら CPU 版のホイールをインストールしています。

バッチ処理

from pathlib import Path
        from paddleocr import PaddleOCR

        ocr = PaddleOCR(lang="en", use_doc_orientation_classify=False, use_doc_unwarping=False)
        files = sorted(str(p) for p in Path("scans").glob("*.jpg"))

        # predict() はリストを受け取り、入力ごとに 1 つの結果を返す
        for res in ocr.predict(files):
            name = Path(res["input_path"]).stem
            res.save_to_json(f"output/{name}")

カスタムモデル

自分で学習またはエクスポートしたモデルは、ディレクトリを指定して使えます：PaddleOCR(text_detection_model_dir="./my_det", text_recognition_model_dir="./my_rec")。必要に応じて text_detection_model_name / text_recognition_model_name も併用します。学習とファインチューニングは本家ドキュメントで説明されています。印刷テキストの大半では、学習よりもしきい値や前処理の調整のほうが、手軽で最初に試すのに向いています。

RAG と LLM パイプライン

検索拡張生成（RAG）では、文書を Markdown に解析し、見出しで分割して、チャンクを埋め込みます。PP-StructureV3 と PaddleOCR-VL は見出しを考慮した Markdown を出力するため、生の OCR 行を分割するよりもチャンク分割がずっときれいになります。

from pathlib import Path
        from paddleocr import PPStructureV3

        pipeline = PPStructureV3(lang="en")
        md_parts = []
        for res in pipeline.predict("handbook.pdf"):
            res.save_to_markdown(save_path="md")

        text = "\n\n".join(p.read_text(encoding="utf-8") for p in sorted(Path("md").glob("*.md")))

        # レベル 2 の見出しで分割。好みのスプリッターに置き換えてください
        chunks = [c.strip() for c in text.split("\n## ") if c.strip()]
        print(len(chunks), "chunks")

• 回答で出典を示せるよう、ページ番号と元ファイルをチャンクのメタデータに残します。
• 品質の低いスキャンでは OCR の信頼度を保存し、信頼度の低いチャンクにフラグを付けます。
• 抽出された数値が正しいとは決して思い込まないでください。請求書や財務書類では、合計・日付・チェックサムなどを検証します。

Dify、RAGFlow などのプラットフォーム

ノーコードのプラットフォームの多くは、HTTP 経由で OCR を呼び出します。PaddleOCR をサービスとして動かし（Docker と下のサービング API を参照）、プラットフォームの HTTP / ツールノードから呼び出すか、プラットフォームに PaddleOCR コネクタが付属していればそれを使います。コネクタの名前やオプションは頻繁に変わるため、プラットフォームの最新のドキュメントを確認してください。

HTTP でサービングする

paddlex --install serving
        paddlex --serve --pipeline OCR          # 既定ではポート 8080 で待ち受け

import base64, requests

        with open("demo.jpg", "rb") as f:
            payload = {"file": base64.b64encode(f.read()).decode("ascii"), "fileType": 1}  # 1 = 画像、0 = PDF

        r = requests.post("http://localhost:8080/ocr", json=payload, timeout=120)
        r.raise_for_status()
        for res in r.json()["result"]["ocrResults"]:
            print(res["prunedResult"])

詳細、認証、スケーリングのオプションは、本家のサービングガイドにあります。独自の認証レイヤーなしで、このポートをインターネットに公開しないでください。

AI エージェント向け MCP サーバー

本家の paddleocr-mcp パッケージ（執筆時点で 0.8.5、Python 3.10 以上）は、OCR、PP-StructureV3、PaddleOCR-VL を Model Context Protocol のツールとして公開します。これにより Claude Desktop などのホストが画像や PDF を読み取れるようになります。

python -m pip install "paddleocr-mcp[local-cpu]"      # ローカルの CPU 推論
        # または: python -m pip install paddleocr-mcp               # ホスト型 / セルフホスト型バックエンドのみ使用

モデルは --model（または PADDLEOCR_MCP_MODEL）で選びます：PP-OCRv6（既定）、PP-OCRv5、PP-OCRv5-latin、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6。推論の実行場所は --ppocr_source で選びます：local（既定）、aistudio、qianfan、self_hosted。stdio の代わりに Streamable HTTP を使うには --http を指定します（既定では 127.0.0.1:8000 にバインド）。

{
          "mcpServers": {
            "paddleocr": {
              "command": "paddleocr_mcp",
              "args": ["--model", "PP-OCRv6", "--ppocr_source", "local"]
            }
          }
        }

プライバシー：local ではファイルは手元のマシンから出ません。aistudio や qianfan では、文書がそれらのサービスにアップロードされます。慎重に選んでください。

JavaScript とブラウザ OCR

@paddleocr/paddleocr-js（執筆時点で 0.4.2、Apache-2.0）は、ONNX Runtime Web と OpenCV.js を使ってブラウザ内で PaddleOCR のモデルを実行します。画像がユーザーの端末から出ることはありません。まだ新しいパッケージ（バージョン 0.x）なので、バージョンを固定し、API の変更を想定してください。

npm install @paddleocr/paddleocr-js

import { PaddleOCR } from "@paddleocr/paddleocr-js";

        const ocr = await PaddleOCR.create({
          lang: "ch",
          ocrVersion: "PP-OCRv5",
          ortOptions: { backend: "auto" },
        });

        const [result] = await ocr.predict(fileOrBlob);   // predict() は配列を返す（画像ごとに 1 要素）
        console.log(result.items);

ocrVersion: "PP-OCRv6" を指定すると、SDK は PP-OCRv6 の small のペアを使います。tiny を使うには、textDetectionModelName: "PP-OCRv6_tiny_det" と textRecognitionModelName: "PP-OCRv6_tiny_rec" を渡します。モデルのアーカイブや WASM ファイルのセルフホストにも対応しています。パッケージの README を参照してください。モバイル回線ではモデルのダウンロードサイズと初回読み込み時間が影響するため、読み込み中の状態を表示してください。

Docker

最小構成の CPU コンテナの例です。これは例示用のレシピであり、本家提供のイメージではありません。お使いのベースイメージとハードウェアでテストしてください。

FROM python:3.12-slim

        # OpenCV のランタイムライブラリ（"libGL.so.1" や "libgthread" のエラーが出る場合に必要）
        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.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ \
            && python -m pip install --no-cache-dir "paddleocr[all]"

        WORKDIR /app
        COPY app.py .
        CMD ["python", "app.py"]

• モデルをキャッシュする。コンテナの起動ごとに重みを再ダウンロードしないよう、~/.paddlex（モデルのキャッシュ先）にボリュームをマウントします。
• GPU：CUDA のベースイメージを使い、CUDA のインデックスから paddlepaddle-gpu のホイールをインストールして、--gpus all を付けて実行します（ホストに NVIDIA Container Toolkit が必要です）。
• エアギャップ環境：モデルを事前にダウンロードし、*_model_dir 引数を渡します。

Python API リファレンス

すべてのパイプラインのメソッド

predict(input, **kwargs)generator/list

推論を実行します。input にはパス、URL、numpy 配列、ディレクトリ、またはそれらのリストを指定でき、PDF にも対応しています。呼び出し時のキーワード引数は、その呼び出しに限りコンストラクタの既定値を上書きします。

predict_iter(input, **kwargs)generator

大きな入力向けの遅延評価版です。

結果オブジェクト

res["rec_texts"] …dict-like

フィールドは辞書のように読み取ります（結果のフィールドを参照）。

res.print()method

結果を整形して表示します。

res.save_to_json(path)method

構造化された JSON を書き出します。

res.save_to_img(path)method

注釈付き画像を書き出します（OCR パイプライン）。

res.save_to_markdown(path)method

Markdown を書き出します（文書解析パイプライン）。

パラメータの正式な一覧は、本家の各パイプラインのページにあります：OCR、PP-StructureV3、PaddleOCR-VL。

コマンドラインリファレンス

paddleocr ocr -i ./scan.png --lang en --device gpu:0 --save_path ./output
        paddleocr ocr -i ./scan.png --ocr_version PP-OCRv5
        paddleocr ocr -i ./scan.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False
        paddleocr pp_structurev3 -i report.pdf --device cpu --save_path ./output
        paddleocr doc_parser -i page.png --save_path ./output

フラグは Python のコンストラクタ引数に対応しています：-i/--input、--lang、--ocr_version、--device、--save_path、そして --use_* の各スイッチ。お使いのバージョンが対応するフラグの一覧は paddleocr ocr --help で確認できます。2.x の古いフラグ --image_dir、--use_gpu、--use_angle_cls は使えなくなりました。

言語コード

lang にコードを渡します。主な値は次のとおりです。

バージョンごとの完全な対応表は、本家の OCR パイプラインのページの付録にあります。対応言語はリリースごとに変わるため、それを正としてください。

トラブルシューティング

ValueError: Unknown argument: use_gpu

2.x のチュートリアルを 3.x で使っています。PaddleOCR(device="gpu") を使ってください。移行を参照してください。

pip が一致する paddlepaddle-gpu を見つけられない

PyPI には古い 2.6.2 の GPU 版しかありません。PaddlePaddle のインデックスから -i https://www.paddlepaddle.org.cn/packages/stable/cu126/（または必要な CUDA バージョン）を指定してインストールしてください。

GPU があるのに CPU で動く

CPU 版のホイールをインストールしたか、device="cpu" を渡している可能性があります。python -c "import paddle; print(paddle.device.get_device())" と nvidia-smi を確認してください。

初回実行が非常に遅い

モデルをダウンロードして初期化しているためです。2 回目以降はキャッシュが再利用されます。サービスでは、単一の PaddleOCR オブジェクトを使い回してください。

結果が空、または文字化けする

• 文字体系に対して lang が違う：韓国語、アラビア語、ロシア語は、PP-OCRv6 の 50 言語モデルに含まれていません。
• 文字が小さい：画像を拡大するか、text_det_limit_side_len を上げます。
• 文字が薄い：text_det_thresh と text_det_box_thresh を少し下げます。
• 撮影したページ：use_doc_unwarping を有効にします。スキャンやスクリーンショットでは無効にします。

ImportError: libGL.so.1（Linux / Docker）

OpenCV のランタイムライブラリをインストールしてください：apt-get install -y libgl1 libglib2.0-0。

GPU のメモリ不足

バッチサイズを下げる、1 ページずつ処理する、より小さいティアを使う、または PaddleOCR-VL を専用の推論サーバーの背後で動かしてください。

それでも解決しませんか？本家のイシュートラッカーを検索し、PaddleOCR と PaddlePaddle のバージョンを添えて報告してください。

リリース履歴

日付は paddleocr パッケージの PyPI へのアップロード日です。詳しいリリースノートは GitHub のリリースページにあります。

HPD-Parsing は 2026年7月22日に発表されました（モデルの発表であり、PyPI のリリースではありません）。