On this page
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#
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.jsonThe 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 ./outputNo 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#
| Pipeline | Python class | CLI | Extra needed | You get |
|---|---|---|---|---|
| Text OCR (PP-OCRv6) | PaddleOCR | paddleocr ocr | none | Lines, boxes, confidences |
| PP-StructureV3 | PPStructureV3 | paddleocr pp_structurev3 | [doc-parser] | Markdown/JSON with layout, tables, formulas |
| PaddleOCR-VL | PaddleOCRVL | paddleocr 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
| Parameter | Effective default | What it does |
|---|---|---|
lang | None → PP-OCRv6 medium | Language code, e.g. "en", "japan", "korean". Picks the recognition model. All 112 codes. |
ocr_version | None | "PP-OCRv6", "PP-OCRv5", "PP-OCRv4" or "PP-OCRv3". Anything else raises ValueError. |
text_detection_model_name / text_recognition_model_name | PP-OCRv6_medium_det / _rec | Choose a model directly — the only way to get the small or tiny tier. Overrides lang/ocr_version. |
text_detection_model_dir / text_recognition_model_dir | None | Load models from a local folder (offline or fine-tuned). |
use_doc_orientation_classify | True | Rotate whole pages by 0/90/180/270° first. |
use_doc_unwarping | True | Flatten curved/photographed pages with UVDoc first. Changes coordinates. |
use_textline_orientation | True | Detect upside-down text lines (0°/180°). |
text_det_limit_side_len / text_det_limit_type | 64 / "min" | Resize rule before detection. "max" caps the longest side instead. |
text_det_thresh | 0.3 | Pixel threshold on the text probability map. |
text_det_box_thresh | 0.6 | Keep a box if its mean score exceeds this. Lower it to catch faint text. |
text_det_unclip_ratio | 1.5 docs say 2.0 | How far boxes are expanded. Raise it if characters get clipped. |
text_rec_score_thresh | 0.0 | Drop recognised lines below this confidence (kept if ≥). |
text_recognition_batch_size | 6 docs say 1 | Lines recognised per batch. |
textline_orientation_batch_size | 6 docs say 1 | Lines classified per batch. |
return_word_box | False | Also return per-word boxes (text_word, text_word_boxes). |
device | None (GPU 0 if available, else CPU) | "cpu", "gpu", "gpu:1", "npu:0"… |
engine | None (PaddlePaddle in most cases) | "paddle", "paddle_static", "paddle_dynamic", "onnxruntime", "transformers". |
enable_mkldnn / cpu_threads | True / 10 | CPU acceleration (oneDNN) and thread count for PaddlePaddle. |
enable_hpi, use_tensorrt, precision | None, 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 input | use_doc_orientation_classify | use_doc_unwarping | use_textline_orientation |
|---|---|---|---|
| Scans, PDFs, screenshots | False | False | False |
| Phone photos of flat pages | False | False | True |
| Pages that may be sideways or upside down | True | False | True |
| Curled book pages, crumpled receipts | True | True | True |
Milliseconds per image, high-performance mode, Intel Xeon Gold 6271C, as published in the PaddleOCR docs. Lower is cheaper.
| Model | CPU 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 |
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 withpage_indexset; - 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:
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):
{
"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], "…"]
}| Field | Meaning |
|---|---|
rec_texts | Recognised text, one string per line (only lines with score ≥ text_rec_score_thresh). |
rec_scores | Confidence per line, 0–1. |
rec_polys | 4-point polygon per kept line (handles rotated text). |
rec_boxes | Axis-aligned [x_min, y_min, x_max, y_max] per kept line; a numpy array of shape (n, 4) in Python. |
dt_polys | All detected polygons, before the score filter. |
textline_orientation_angles | 0 or 1 (180°) per line; −1 when the classifier is off. |
doc_preprocessor_res | Page rotation applied (angle 0–3 for 0/90/180/270°, −1 when off). |
page_index | Page number for PDF input, otherwise null. |
text_word, text_word_boxes | Only 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 callpredictmany times. - Pass folders or lists rather than looping in Python, and use
predict_iterfor 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).
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):
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
| Kind | Subcommands |
|---|---|
| Pipelines | ocr, pp_structurev3, doc_parser (PaddleOCR-VL), doc_preprocessor, table_recognition_v2, seal_recognition, formula_recognition_pipeline, doc_understanding, pp_chatocrv4_doc, pp_doctranslation |
| Single models | text_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 |
| Utilities | install_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:
# 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 --helpLogging#
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
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
- 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. - Effective defaults: PaddleX 3.7.2
paddlex/configs/pipelines/OCR.yamlandpaddlex/inference/pipelines/ocr/pipeline.py, as installed bypip install paddleocr==3.7.0. - Official OCR pipeline guide: docs/version3.x/pipeline_usage/OCR.en.md (parameter descriptions, accepted inputs, output files).
- Result object methods: PaddleX
paddlex/inference/common/result/mixin.pyandpaddlex/inference/pipelines/ocr/result.py. - Logging: logging.en.md vs
paddleocr/_env.py. - Our tests (2026-10-27, PaddleOCR 3.7.0, Linux, 4 vCPU): real
save_to_jsonoutput, coordinate shift withuse_doc_unwarping=True, preprocessing cost. Scripts in our benchmark. - Preprocessing model latencies: official OCR pipeline guide tables (Intel Xeon Gold 6271C CPU / NVIDIA T4).