Start here

Quick start & APIInstallOnline OCRCode generator

Models & pipelines

PP-OCRv6 modelsLanguagesPP-StructureV3PaddleOCR-VL

Deploy & integrate

Serving & APIPaddleOCR.jsMCP server

Fix & upgrade

TroubleshootingMigrate from 2.xReleases

Evaluate

Our benchmarkCompare OCR toolsLicense & cost

Tools

Online OCRInstall command builderCode generatorError fixer2.x → 3.x converterLanguage code finder

Language

English简体中文日本語Try OCR online
Documentation

PaddleOCR 3.7 quick start & Python API

Everything you need to call PaddleOCR from Python or the command line: a working first script, every constructor parameter with its effective default (the docs and the code disagree on some), the result object, PDFs, batching and the CLI.

Checked against PaddleOCR 3.7.0Updated 14 min read
On this page
  1. Quick start: your first OCR
  2. The three pipelines at a glance
  3. PaddleOCR() parameters — with the defaults that actually apply
  4. predict(): inputs and per-call overrides
  5. The result object
  6. Batches, folders and speed
  7. Single-model classes and custom models
  8. Command-line reference
  9. Logging
  10. Where to go next
  11. FAQ

The 30-second version: install an engine and PaddleOCR (install guide), then PaddleOCR().predict("image.png"). Each result is a dict-like object: read rec_texts, rec_scores and rec_boxes, or call save_to_json() and save_to_img(). For Markdown, tables and formulas, use PPStructureV3 instead.

Quick start: your first OCR#

pythonfirst_ocr.py
from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,  # skip page-rotation model (clean scans)
    use_doc_unwarping=False,             # skip page-flattening model (flat pages)
    use_textline_orientation=False,      # skip upside-down line detection
)
for res in ocr.predict("receipt.jpg"):
    res.print()                  # pretty-print every field
    res.save_to_img("output")    # output/receipt_ocr_res_img.jpg with boxes drawn
    res.save_to_json("output")   # output/receipt_res.json

The first call downloads PP-OCRv6 medium (detection + recognition) into ~/.paddlex/official_models. Everything after that runs offline. The same thing from a terminal:

paddleocr ocr -i receipt.jpg --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./output

No GPU? That's fine — this ran in about 3.2 s per receipt with PaddlePaddle 3.2.0 on our 4-core test machine (2.0 s with ONNX Runtime). See the benchmark for every model.

The three pipelines at a glance#

PipelinePython classCLIExtra neededYou get
Text OCR (PP-OCRv6)PaddleOCRpaddleocr ocrnoneLines, boxes, confidences
PP-StructureV3PPStructureV3paddleocr pp_structurev3[doc-parser]Markdown/JSON with layout, tables, formulas
PaddleOCR-VLPaddleOCRVLpaddleocr doc_parser[doc-parser]Markdown/JSON from a vision-language model

There are more pipelines (seal recognition, table recognition, formula recognition, PP-ChatOCRv4 key-information extraction, PP-DocTranslation) and single-model classes such as TextDetection and TextRecognition; the CLI section lists all of them.1

PaddleOCR() parameters — with the defaults that actually apply#

Every OCR-specific argument in PaddleOCR.__init__ defaults to None, which means "use the value from PaddleX's pipeline config". So the real defaults live in PaddleX's OCR.yaml, not in the PaddleOCR signature — and in three places they differ from the official docs.12

ParameterEffective defaultWhat it does
langNone → PP-OCRv6 mediumLanguage code, e.g. "en", "japan", "korean". Picks the recognition model. All 112 codes.
ocr_versionNone"PP-OCRv6", "PP-OCRv5", "PP-OCRv4" or "PP-OCRv3". Anything else raises ValueError.
text_detection_model_name / text_recognition_model_namePP-OCRv6_medium_det / _recChoose a model directly — the only way to get the small or tiny tier. Overrides lang/ocr_version.
text_detection_model_dir / text_recognition_model_dirNoneLoad models from a local folder (offline or fine-tuned).
use_doc_orientation_classifyTrueRotate whole pages by 0/90/180/270° first.
use_doc_unwarpingTrueFlatten curved/photographed pages with UVDoc first. Changes coordinates.
use_textline_orientationTrueDetect upside-down text lines (0°/180°).
text_det_limit_side_len / text_det_limit_type64 / "min"Resize rule before detection. "max" caps the longest side instead.
text_det_thresh0.3Pixel threshold on the text probability map.
text_det_box_thresh0.6Keep a box if its mean score exceeds this. Lower it to catch faint text.
text_det_unclip_ratio1.5 docs say 2.0How far boxes are expanded. Raise it if characters get clipped.
text_rec_score_thresh0.0Drop recognised lines below this confidence (kept if ≥).
text_recognition_batch_size6 docs say 1Lines recognised per batch.
textline_orientation_batch_size6 docs say 1Lines classified per batch.
return_word_boxFalseAlso return per-word boxes (text_word, text_word_boxes).
deviceNone (GPU 0 if available, else CPU)"cpu", "gpu", "gpu:1", "npu:0"…
engineNone (PaddlePaddle in most cases)"paddle", "paddle_static", "paddle_dynamic", "onnxruntime", "transformers".
enable_mkldnn / cpu_threadsTrue / 10CPU acceleration (oneDNN) and thread count for PaddlePaddle.
enable_hpi, use_tensorrt, precisionNone, False, "fp32"High-performance inference, TensorRT, "fp16".

Any other keyword raises ValueError: Unknown argument: …. Eleven 2.x names (use_angle_cls, det_db_thresh, rec_model_dir…) are still accepted by PaddleOCR with a deprecation warning; use_gpu, show_log and others are not. Our migration guide lists every one.1

Should you keep the three preprocessing models on?#

By default, PaddleOCR() runs two page-level models (orientation and UVDoc unwarping) and one line-level model before recognition. They help with photographed, rotated or curved pages and cost time on clean scans and screenshots. Turn them off when your inputs are flat and upright — as in every example on this site — and turn on just the one you need otherwise:

Your inputuse_doc_orientation_classifyuse_doc_unwarpinguse_textline_orientation
Scans, PDFs, screenshotsFalseFalseFalse
Phone photos of flat pagesFalseFalseTrue
Pages that may be sideways or upside downTrueFalseTrue
Curled book pages, crumpled receiptsTrueTrueTrue
Official CPU latency of each preprocessing model

Milliseconds per image, high-performance mode, Intel Xeon Gold 6271C, as published in the PaddleOCR docs. Lower is cheaper.

ModelCPU ms
Text line orientation (PP-LCNet_x1_0_textline_ori)2.98 ms
Page orientation (PP-LCNet_x1_0_doc_ori)1.19 ms
Page unwarping (UVDoc)869.82 ms
PaddleOCR OCR pipeline docs (docs/version3.x/pipeline_usage/OCR.en.md) and module docs. Vendor-published figures.

The two orientation classifiers are nearly free; UVDoc unwarping is the expensive one — roughly 0.9 s per image on a server CPU by the official numbers — and it also changes your coordinates (next section). If you only switch off one thing, switch off use_doc_unwarping.

Gotcha: unwarping changes the coordinates#

When use_doc_unwarping=True (the default), detection runs on the flattened image, and every box is reported in that image's coordinates. We ran the same receipt both ways: the first line came back as [[119, 11], [507, 8], [507, 46], [120, 49]] with unwarping on and [[128, 55], [489, 55], [489, 82], [128, 82]] with it off. Draw the first set on your original image and the boxes land in the wrong place.6

Either turn unwarping off, or draw on the preprocessed image the result carries: res.img["preprocessed_img"] (present when the document preprocessor ran — we checked: res.img then has the keys ocr_res_img and preprocessed_img).46

predict(): inputs and per-call overrides#

predict(input) returns a list of results; predict_iter(input) yields them one at a time, which keeps memory flat on long PDFs and big folders. input can be:3

  • a path or URL to an image (.jpg, .png, …) or a PDF — each page becomes one result with page_index set;
  • a directory of images (PDFs inside directories are not supported);
  • a numpy array (BGR, as from cv2.imread);
  • a list of any of the above.

Detection and recognition thresholds, the three preprocessing switches and return_word_box can be overridden per call — useful for retrying a hard image without rebuilding the pipeline:

python
res = ocr.predict("faded_label.jpg", text_det_box_thresh=0.4, text_det_unclip_ratio=2.0)[0]

You can't switch on at predict() time a model you switched off at construction. With PaddleOCR(use_textline_orientation=False), calling predict(..., use_textline_orientation=True) logs an error and yields {"error": ...} instead of a result.2

The result object#

Each result is a dict subclass (OCRResult), so res["rec_texts"] works, and it has helper methods. Here is the real JSON PaddleOCR 3.7.0 wrote for our test receipt (arrays shortened):

jsonoutput/receipt_res.json (from our run)
{
  "input_path": "samples/receipt.png",
  "page_index": null,
  "model_settings": {"use_doc_preprocessor": true, "use_textline_orientation": true},
  "doc_preprocessor_res": {"model_settings": {"use_doc_orientation_classify": true, "use_doc_unwarping": true}, "angle": 0},
  "dt_polys": [[[119, 11], [507, 8], [507, 46], [120, 49]], "…"],
  "text_det_params": {"limit_side_len": 64, "limit_type": "min", "thresh": 0.3,
                      "max_side_limit": 4000, "box_thresh": 0.6, "unclip_ratio": 1.5},
  "text_type": "general",
  "textline_orientation_angles": [0, 0, "…"],
  "text_rec_score_thresh": 0.0,
  "return_word_box": false,
  "rec_texts": ["HARBOR STREET COFFEE", "214 Harbor Street, Portland ME", "…"],
  "rec_scores": [0.9999498128890991, 0.9985201954841614, "…"],
  "rec_polys": [[[119, 11], [507, 8], [507, 46], [120, 49]], "…"],
  "rec_boxes": [[119, 8, 507, 49], [120, 57, 506, 87], "…"]
}
FieldMeaning
rec_textsRecognised text, one string per line (only lines with score ≥ text_rec_score_thresh).
rec_scoresConfidence per line, 0–1.
rec_polys4-point polygon per kept line (handles rotated text).
rec_boxesAxis-aligned [x_min, y_min, x_max, y_max] per kept line; a numpy array of shape (n, 4) in Python.
dt_polysAll detected polygons, before the score filter.
textline_orientation_angles0 or 1 (180°) per line; −1 when the classifier is off.
doc_preprocessor_resPage rotation applied (angle 0–3 for 0/90/180/270°, −1 when off).
page_indexPage number for PDF input, otherwise null.
text_word, text_word_boxesOnly with return_word_box=True.

Methods: print(json_format=False, indent=4, ensure_ascii=False), save_to_json(path) (writes {name}_res.json), save_to_img(path) (writes {name}_ocr_res_img.{ext}), save_all(path), and the properties json, str and img. Note the official docs call the print argument format_json; the code uses json_format.4

Common recipes#

res = ocr.predict("invoice.png")[0]
for text, score, box in zip(res["rec_texts"], res["rec_scores"], res["rec_boxes"]):
    if score >= 0.80:
        x1, y1, x2, y2 = box.tolist()
        print(f"{score:.2f}  {text}  @ ({x1},{y1})-({x2},{y2})")
res = ocr.predict("page.png")[0]
lines = sorted(zip(res["rec_boxes"].tolist(), res["rec_texts"]), key=lambda t: (t[0][1], t[0][0]))
print("\n".join(text for _, text in lines))
from paddleocr import PaddleOCR

ocr = PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False)
with open("report.txt", "w", encoding="utf-8") as f:
    for res in ocr.predict_iter("report.pdf"):        # one result per page
        f.write(f"--- page {res['page_index'] + 1} ---\n")
        f.write("\n".join(res["rec_texts"]) + "\n")
import cv2
img = cv2.imread("photo.jpg")            # BGR numpy array
res = ocr.predict(img)[0]

The "top to bottom" sort is a simple heuristic for single-column text. For multi-column pages, tables or true reading order, use PP-StructureV3, which computes reading order from the layout.

Batches, folders and speed#

  • Reuse one instance. Creating PaddleOCR() loads models; do it once and call predict many times.
  • Pass folders or lists rather than looping in Python, and use predict_iter for large inputs.
  • Pick the tier for your hardware: small was 3.3–3.7× faster than medium on our CPU, with 2 more errors in 124 text items. Model guide.
  • Try ONNX Runtime on CPU (engine="onnxruntime"): 1.4–1.5× faster for PP-OCRv6 in our test.
  • Turn off preprocessing you don't need (above).
python
ocr = PaddleOCR(
    text_detection_model_name="PP-OCRv6_small_det",
    text_recognition_model_name="PP-OCRv6_small_rec",
    use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False,
    engine="onnxruntime",
)
for res in ocr.predict_iter("scans/"):
    res.save_to_json("output")

Single-model classes and custom models#

3.x exposes each model as its own class — the replacement for 2.x's ocr(img, det=False) and ocr(img, rec=False):

python
from paddleocr import TextDetection, TextRecognition

det = TextDetection(model_name="PP-OCRv6_medium_det")
for res in det.predict("receipt.jpg"):
    print(res["dt_polys"], res["dt_scores"])   # boxes and their scores

rec = TextRecognition(model_name="PP-OCRv6_medium_rec")
for res in rec.predict("cropped_line.png"):
    print(res["rec_text"], res["rec_score"])

Fine-tuned or exported models load through the *_model_dir arguments, e.g. PaddleOCR(text_recognition_model_dir="./my_rec_model").

Command-line reference#

The 3.x CLI uses subcommands. The 2.x style (paddleocr --image_dir x.jpg --use_angle_cls true) no longer works.1

KindSubcommands
Pipelinesocr, pp_structurev3, doc_parser (PaddleOCR-VL), doc_preprocessor, table_recognition_v2, seal_recognition, formula_recognition_pipeline, doc_understanding, pp_chatocrv4_doc, pp_doctranslation
Single modelstext_detection, text_recognition, textline_orientation_classification, doc_img_orientation_classification, text_image_unwarping, layout_detection, table_structure_recognition, table_cells_detection, table_classification, formula_recognition, seal_text_detection, chart_parsing, doc_vlm
Utilitiesinstall_hpi_deps {cpu,gpu,npu}, install_genai_server_deps {vllm,sglang,fastdeploy}, genai_server, doc2md, api

Pipeline flags mirror the Python parameter names, with booleans written as True/False:

bash
# OCR a folder of scans on GPU 0 with the small tier, results to ./out
paddleocr ocr -i ./scans --device gpu:0 \
  --text_detection_model_name PP-OCRv6_small_det \
  --text_recognition_model_name PP-OCRv6_small_rec \
  --use_doc_orientation_classify False --use_doc_unwarping False \
  --save_path ./out

# Korean, CPU, ONNX Runtime engine
paddleocr ocr -i sign.jpg --lang korean --engine onnxruntime

# A PDF to Markdown with PP-StructureV3
paddleocr pp_structurev3 -i report.pdf --save_path ./out

# Help for any subcommand
paddleocr ocr --help

Logging#

PaddleOCR logs through one logger, paddleocr.logger, at level ERROR by default, so it's quiet unless something fails. To raise the level or log to a file:5

python
import logging
from paddleocr import logger

logger.setLevel(logging.INFO)
logger.addHandler(logging.FileHandler("paddleocr.log"))

To stop PaddleOCR configuring its logger at all, the docs say to set DISABLE_AUTO_LOGGING_CONFIG=1 — but the code reads PADDLEOCR_DISABLE_AUTO_LOGGING_CONFIG=1. Use the prefixed name.5 PaddleX's green "Creating model" messages come from PaddleX's own logger and aren't affected.

Where to go next#

PP-StructureV3#

PDFs and scans to Markdown with tables and formulas.

Serving & API#

Expose any pipeline over HTTP, or call the hosted API.

Troubleshooting#

Paste an error message and get a verified fix.

Code generator#

Build a script with just the options you need.

FAQ#

What's the difference between ocr() and predict()?

ocr() is the 2.x method name. In 3.x it still exists as a deprecated alias that returns the same result objects as predict(), but it no longer accepts cls=, det= or rec=: in our test ocr(img, cls=True) raised TypeError: PaddleOCR.predict() got an unexpected keyword argument 'cls'. Use predict() (or predict_iter()) and read fields from the result object.

How do I get just the text out of a PaddleOCR result?

"\n".join(res["rec_texts"]). Each entry is one detected line, in detection order.

Can PaddleOCR read PDFs directly?

Yes. Pass the PDF path to predict() or predict_iter(); each page becomes one result with page_index set. For Markdown output with layout and tables, use PP-StructureV3.

Why are my boxes in the wrong place when I draw them on the image?

Most likely use_doc_unwarping is on (the default), so coordinates refer to the flattened image. Turn it off or draw on res.img["preprocessed_img"].

How do I use the small or tiny PP-OCRv6 model?

Pass both names: text_detection_model_name="PP-OCRv6_small_det" and text_recognition_model_name="PP-OCRv6_small_rec". lang and ocr_version only ever select the medium tier.

Is there a PaddleOCR API reference for every parameter?

This page covers the OCR pipeline. The official guide at paddleocr.ai documents every pipeline and module; where its defaults disagree with the shipped config, we've noted it above.

Sources

  1. PaddleOCR 3.7.0 source: paddleocr/_pipelines/ocr.py (constructor, legacy-name mapping, ocr() deprecation), paddleocr/_common_args.py (engine, device, unknown-argument error), paddleocr/_cli.py (subcommands) — github.com/PaddlePaddle/PaddleOCR.
  2. Effective defaults: PaddleX 3.7.2 paddlex/configs/pipelines/OCR.yaml and paddlex/inference/pipelines/ocr/pipeline.py, as installed by pip install paddleocr==3.7.0.
  3. Official OCR pipeline guide: docs/version3.x/pipeline_usage/OCR.en.md (parameter descriptions, accepted inputs, output files).
  4. Result object methods: PaddleX paddlex/inference/common/result/mixin.py and paddlex/inference/pipelines/ocr/result.py.
  5. Logging: logging.en.md vs paddleocr/_env.py.
  6. Our tests (2026-10-27, PaddleOCR 3.7.0, Linux, 4 vCPU): real save_to_json output, coordinate shift with use_doc_unwarping=True, preprocessing cost. Scripts in our benchmark.
  7. Preprocessing model latencies: official OCR pipeline guide tables (Intel Xeon Gold 6271C CPU / NVIDIA T4).
Updated October 27, 2026·How we verify facts