Migrate PaddleOCR 2.x code to 3.x

2.x → 3.x code converter#

The converter is rule-based, not a guess. It rewrites only patterns it understands, cites the PaddleOCR source line for each change, and leaves a # TODO(paddleocr 3.x) comment wherever a human has to decide. We ran its output for the first two examples on PaddleOCR 3.7.0: both ran without errors and read all 27 lines of our test receipt, and the first wrote result.jpg.⁷

What changed in 3.x, and why#

PaddleOCR 2.x grew from 2021 to early 2025 by adding features to one lightweight code base. The maintainers' upgrade notes say that approach hit a wall: duplicated code, inconsistent interfaces and old dependencies that no longer worked with newer PaddlePaddle. Their answer was "a major, non-backward-compatible upgrade".² In 3.x the paddleocr package is a thin wrapper around PaddleX pipelines; PaddleOCR wraps the PaddleX OCR pipeline and returns result objects.¹

1. Sep 15, 2023paddleocr 2.7.0.3 — still a common pin in old requirements.txt files.
2. Mar 7, 2025paddleocr 2.10.0 — the last 2.x release.
3. May 20, 2025paddleocr 3.0.0 — new API on PaddleX.
4. Jun 11, 2026paddleocr 3.7.0 — current release, PP-OCRv6 models by default.

Dates are first-upload dates on PyPI.⁶ If you install paddleocr without a version today you get 3.7.0, so 2.x code breaks the moment a fresh environment is built. These are the changes that break it:

Two more changes don't raise anything but change your output: new default models and preprocessing, covered in defaults that changed silently, and the engine install. pip install paddleocr does not install PaddlePaddle in 3.x, and the PyPI paddlepaddle-gpu package stops at 2.6.2 — see our install guide.

use_angle_cls and the 11 names that still work#

3.x keeps a small translation table for old PaddleOCR keyword arguments. This is the complete list, copied from the source:¹

_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",
}

Pass one of these and 3.x renames it for you, with a warning. We ran PaddleOCR(lang='en', use_angle_cls=True) on 3.7.0 and got exactly this:⁷

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

Python hides DeprecationWarning by default unless it is triggered from __main__, so many people never see it. Three rules follow from the code around that table:¹

• Old and new name together is an error. PaddleOCR(use_angle_cls=True, use_textline_orientation=True) raises ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive. (we reproduced it).
• Only PaddleOCR has the table. PPStructureV3(det_model_dir=...) and PPStructureV3(use_angle_cls=True) raise ValueError: Unknown argument: det_model_dir / use_angle_cls. We reproduced both.
• "Still works" isn't "same behaviour". In 2.x use_angle_cls defaulted to False. In 3.x, leaving use_textline_orientation unset means the pipeline default, which is True.⁵

The same 11 exist as CLI flags on paddleocr ocr: --use_angle_cls still works and prints 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: errors, not warnings#

Every other leftover keyword hits this loop, which accepts only the 3.x engine options:¹

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

Because it raises on the first name it finds, and unknown_names is a set, a constructor with three stale arguments reports only one of them per run. Fix them all at once with the table below, or with the converter. Our reproduction on 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

A common mistake in the other direction: device='cuda'. PaddleX rejects it with a bare AssertionError; the GPU device type is called gpu.

ocr(img, cls=True) and the new result format#

3.x still has an ocr() method, but it is a deprecated alias that forwards its keyword arguments to predict():¹

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

predict() has no cls parameter, so the line nearly every 2.x tutorial contains fails. On 3.7.0 we got:⁷

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

Text-line orientation is now chosen when you build the object (use_textline_orientation=True), or per call with predict(img, use_textline_orientation=False). One catch from the PaddleX source: you can switch it off per call, but turning it on per call when the object was built without it logs an error instead of running.

The bigger change is what comes back. In 2.x, ocr() returned one list per image holding [box, (text, score)] per line, or None when no text was found.³ In 3.x, predict() returns one OCRResult per image or PDF page. It is a dict with parallel lists:⁵

What the old loop does against this object is worth knowing, because the error doesn't mention PaddleOCR at all. for line in result[0] now iterates the dict's keys, so the first line is the string 'input_path', and box, (text, score) = line raises ValueError: too many values to unpack (expected 2). Indexing like result[0][0][1][0] raises KeyError: 0. We reproduced both.⁷

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())

Three details trip people up after converting. The polygons are NumPy arrays, so call .tolist() before json.dumps (or use res.json). A page without text gives empty lists, not None, so if result[0] is None never fires — test if not res['rec_texts']. And with the default use_doc_unwarping=True, coordinates refer to the unwarped image: on our receipt the first line was [[119,11],[507,8],[507,46],[120,49]] with unwarping and [[128,55],[489,55],[489,82],[128,82]] without.⁷ More in boxes don't line up.

ocr(img, det=False) and ocr(img, rec=False) have no pipeline equivalent. Use the single-model classes: TextRecognition(model_name="PP-OCRv6_medium_rec").predict(crop) returns rec_text and rec_score; TextDetection(model_name="PP-OCRv6_medium_det").predict(img) returns dt_polys and dt_scores. The converter marks these calls with a TODO rather than guess how your crops are produced.

cannot import name 'draw_ocr' from 'paddleocr'#

draw_ocr was exported by paddleocr 2.10.0 and is not in the 3.x package, so the import fails:⁷

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

Results draw themselves now. The upgrade notes replace the whole visualization block with one call:²

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

On our receipt, save_to_img('output') wrote receipt_ocr_res_img.png and receipt_preprocessed_img.png; res.img has the same two keys.⁷ To use your own font, set the environment variable PADDLE_PDX_LOCAL_FONT_FILE_PATH instead of passing font_path. The other removed helpers map the same way: save_structure_res → res.save_to_json(), save_to_xlsx(), save_to_html() or save_all(); convert_info_docx → res.save_to_word(); to_excel → res.save_to_xlsx().⁵

det_model_dir and rec_model_dir: custom models#

det_model_dir, rec_model_dir and cls_model_dir are three of the 11 aliases, so they still work on PaddleOCR. Two things change underneath:

• Give the model name too. If you set only text_detection_model_dir, the pipeline keeps its default name (PP-OCRv6_medium_det) and PaddleX compares it with the name in the folder's inference.yml: ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir.⁵
• The folder must be a 3.x export. 3.x looks for inference.json or inference.pdmodel plus inference.pdiparams and an inference.yml. A folder without valid files gives No valid model files were found for engine 'paddle_static'.
• Training-time options are gone. rec_char_dict_path, rec_algorithm, det_algorithm, use_space_char and max_text_length raise Unknown argument. Models are chosen by name, and per-module settings go in an exported PaddleX config (export_paddlex_config_to_yaml, then 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',
)

When model names or folders are given, lang and ocr_version are ignored with a UserWarning. Note also that the 2.x script-group values lang='latin', 'arabic', 'cyrillic' and 'devanagari' are not language codes in 3.x: they raise No models are available for lang='latin' and ocr_version=None. Pick a real code from our language list.

Defaults that changed silently#

Code that runs after migration can still give different text, boxes and speed, because the defaults moved:⁵³

The converter's "Keep 2.x behaviour" option adds the four switches the error database recommends for 2.x-like output: use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False and text_rec_score_thresh=0.5. Turning off the preprocessing models also makes 3.x faster. It keeps the new models, which read our five test documents with 123 of 124 items exact (our benchmark).

PPStructure → PPStructureV3#

from paddleocr import PPStructure fails in 3.x with ImportError: cannot import name 'PPStructure' from 'paddleocr'. The upgrade notes point to PPStructureV3, which needs an extra install:²⁸

Without it, PPStructureV3() fails with RuntimeError: A dependency error occurred during pipeline creation (fix). The constructor has its own parameters and no alias table, so even names that work on PaddleOCR fail here. We got Unknown argument: use_gpu, det_model_dir, use_angle_cls and show_log from PPStructureV3 on 3.7.0.⁷

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

A 2.x structure result was a list of region dicts for one image; a 3.x result is one object per page. Our PP-StructureV3 guide covers the output in depth, including which OCR models it uses by default.

Command line: paddleocr --image_dir → paddleocr ocr -i#

The 3.x CLI needs a subcommand and takes the input with -i. The 2.x form fails in an unhelpful way: argparse treats your file name as the subcommand. Our run on 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', ...)

Boolean flags accept true/True/1; anything else counts as false. We ran paddleocr ocr on our receipt with --save_path: it printed the result and wrote the JSON plus both images. Paste a whole shell script into the converter; it rewrites paddleocr and pip install lines and leaves the rest alone.

Complete 2.x → 3.x mapping table#

All 123 entries of our verified mapping, generated from the same data the converter uses. "Alias, warns" means the old name still works; "Rename" means it must change; "Replaced" and "Removed" raise errors if left in. Every row links to the file and line we read.¹³⁵

Imports 13#

PaddleOCR constructor parameters 47#

PPStructure → PPStructureV3 parameters 18#

Methods and result format 12#

Helper functions 9#

Command line 24#

Staying on 2.x: pin paddleocr below 3#

If you can't migrate yet, pin the last 2.x release in its own virtual environment:

That resolves to 2.10.0. Like 3.x, its wheel does not list PaddlePaddle as a dependency, so you install a framework yourself.³ We have not tested which PaddlePaddle 3.x versions run paddleocr 2.x, so if you already have a working 2.x environment, freeze it (pip freeze > requirements.txt) rather than rebuilding it. Code that imports 2.x internals (paddleocr.tools, paddleocr.ppocr, paddleocr.ppstructure) can only run on 2.x: those modules are not in the 3.x package.

The cost of waiting grows: 2.x gets no new models, while 3.x moved from PP-OCRv5 to PP-OCRv6 and added PaddleOCR-VL.

Migration checklist#

1. New environment, new engine#

   Create a fresh venv. pip install paddleocr, then paddlepaddle==3.2.0 from the PaddlePaddle index, or onnxruntime. The install builder gives the exact commands for your machine.

2. Convert the code#

   Run each file through the converter. Resolve every # TODO(paddleocr 3.x).

3. Turn warnings into errors once#

   Run your tests with python -W error::DeprecationWarning to catch remaining aliases and ocr() calls.

4. Compare outputs#

   Diff texts on a few real documents. If they differ, try the "Keep 2.x behaviour" switches before blaming the models.

5. Check the error you hit#

   Paste anything unexpected into the error fixer.

Questions#