PaddleOCR errors and how to fix them

Error fixer#

Every entry comes from one of two places: the PaddleOCR, PaddleX or PaddlePaddle source code (we cite the file and line), or a run on our own test machine, marked Reproduced by paddleocr.dev. Where official docs give advice that no longer works in 3.x, we say so. All entries are also listed below, so you can link to any of them.⁹

ConvertPirAttribute2RuntimeAttribute not support pir::ArrayAttribute (oneDNN crash)#

Reproduced by paddleocr.dev This is the error you get today if you follow the obvious install steps on a CPU machine: pip install paddleocr paddlepaddle, then run any OCR.¹

NotImplementedError: (Unimplemented) ConvertPirAttribute2RuntimeAttribute not support [pir::ArrayAttribute<pir::DoubleAttribute>]  (at /paddle/paddle/fluid/framework/new_executor/instruction/onednn/onednn_instruction.cc:116)

Why it happens#

Three facts combine. pip install paddlepaddle installs the newest release on PyPI, 3.3.1.⁸ PaddleOCR 3.x turns oneDNN (MKL-DNN) on for CPU by default, enable_mkldnn=True.⁴ And in PaddlePaddle's oneDNN executor, the function ConvertPirAttribute2RuntimeAttribute has no branch for an array-of-doubles attribute in the tagged releases v3.3.0, v3.3.1 and v3.4.0, so it throws Unimplemented at line 116. The develop branch adds the missing branch, but no tagged release we checked contains it.³ The official PaddleOCR docs never mention this error; they pin paddlepaddle==3.2.0, which is why people following them don't hit it.⁶

Three fixes that work#

We tried each one on the same machine and documents.¹²

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
# then run your code unchanged

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', enable_mkldnn=False)
# CLI: paddleocr ocr -i img.png --enable_mkldnn False

# pip install onnxruntime   (PaddlePaddle is not needed at all for this engine)
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', engine='onnxruntime')

• A keeps oneDNN and matches the version the installation guide pins. It needs no code change.
• B is the slowest. It switches the CPU run mode from oneDNN to plain paddle. On our machine it averaged 11.88 s per page versus 4.51 s for oneDNN on PaddlePaddle 3.2.0: 2.6× slower on average, 2.3× to 3.0× depending on the document.
• C was the fastest with the default PP-OCRv6 models: 2.92 s per page. It works with only pip install paddleocr onnxruntime; the first load prints many harmless Removing initializer warnings. One caveat from the same benchmark: with PP-OCRv5_server models ONNX Runtime was far slower (35.70 s vs 5.25 s per page).

All three setups read 123 of 124 ground-truth items exactly, so the choice is about speed, not accuracy. The full method is on our benchmark page, and the install guide shows the pinned commands for every OS. Once a PaddlePaddle release ships the develop-branch fix, upgrading will be a fourth option; we will update this page when one does.

A dependency error occurred during pipeline creation#

Reproduced by paddleocr.dev We got this from PPStructureV3() in an environment with plain pip install paddleocr:¹

RuntimeError: A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.

The message doesn't say what is missing. The real cause is printed earlier in the traceback, just above the line "The above exception was the direct cause of the following exception":

DependencyError: `PP-StructureV3` requires additional dependencies. To install them, run `pip install "paddlex[ocr]==<PADDLEX_VERSION>"` if you're installing `paddlex` from an index, or `pip install -e "/path/to/PaddleX[ocr]"` if you're installing `paddlex` locally.

Basic pip install paddleocr brings only paddlex[ocr-core]. Document parsing needs the doc-parser extra, which pulls paddlex[ocr,genai-client].⁴ You don't need to install PaddleX by hand as the message suggests; install the PaddleOCR extra:

The same error appears for basic OCR if a required package was replaced or removed, because PaddleX checks installed distributions by name with importlib.metadata.⁵ The classic way to cause that is swapping OpenCV for the headless build — see libGL below.

Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed#

RuntimeError: Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed.

pip install paddleocr does not install PaddlePaddle. Its dependencies are paddlex[ocr-core], PyYAML, requests, aiohttp and typing-extensions. With engine unset, PaddleX picks the PaddlePaddle engine and checks for the paddle module.⁴⁵ Install one engine:

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -c "import paddle; print(paddle.__version__)"

# driver >= 550.54.14
python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
# older driver (>= 450.80.02 on Linux, >= 452.39 on Windows): use .../stable/cu118/

python -m pip install onnxruntime
# then: PaddleOCR(engine='onnxruntime')

Pin 3.2.0 on CPU: an unpinned pip install paddlepaddle gets 3.3.1 and the oneDNN crash. For GPU, the PaddlePaddle index is the only source of 3.x wheels: the paddlepaddle-gpu package on PyPI stops at 2.6.2, which PaddleOCR 3.x cannot use.⁸⁶ The official docs say to choose the wheel by GPU driver version, not by the CUDA toolkit installed on the machine. Install only one engine per environment.

ImportError: libGL.so.1: cannot open shared object file#

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

This shows up in slim Docker images and minimal Linux servers. PaddleX's OCR dependencies include opencv-contrib-python==4.10.0.84, the regular (non-headless) OpenCV build, which links against system libGL and glib.⁵ Install those libraries — this is what PaddleOCR's own Dockerfiles do:⁷

apt-get update && apt-get install -y libgl1 libglib2.0-0

The same fix covers libgthread-2.0.so.0 and libglib-2.0.so.0 errors, which come from the glib package.

PaddleOCR doesn't use the GPU#

PaddleOCR 3.x doesn't fail when it can't use the GPU. If you ask for device='gpu' and the installed PaddlePaddle has no CUDA, PaddleX logs one line and carries on with the CPU:⁵

The specified device (GPU) is not available! Switching to CPU instead.

Set PADDLE_PDX_DISABLE_DEVICE_FALLBACK to turn that into a RuntimeError instead. The usual cause is the CPU build of PaddlePaddle: pip install paddlepaddle or pip install paddleocr alone never gives you GPU support, and pip install paddlepaddle-gpu from PyPI gives 2.6.2. Check what you have:

python -c "import paddle; print(paddle.__version__, paddle.is_compiled_with_cuda(), paddle.device.cuda.device_count())"
nvidia-smi

1. If it prints False: pip uninstall paddlepaddle paddlepaddle-gpu, then install paddlepaddle-gpu==3.2.0 from the cu126 or cu118 index above, chosen by driver version.
2. If it prints True but a device count of 0, PaddlePaddle can't see the GPU: check that nvidia-smi lists it.
3. Use device='gpu' or 'gpu:0'; 'cuda' is rejected with an AssertionError.
4. The 2.x way, use_gpu=True, raises ValueError: Unknown argument: use_gpu in 3.x (below).

With engine='onnxruntime', GPU needs onnxruntime-gpu (CUDA 12) and its CUDAExecutionProvider. Library loading errors (libcudnn, libcublas) and RTX 50-series on Windows are covered in the GPU section below.

Upgrading from 2.x#

Unknown argument: use_gpu#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

ValueError: Unknown argument: use_gpu

Cause. 2.x engine options use_gpu / gpu_id / gpu_mem do not exist in 3.x. Every keyword not consumed by the class is validated against device, engine, engine_config, enable_hpi, use_tensorrt, precision, enable_mkldnn, mkldnn_cache_capacity, cpu_threads, enable_cinn.

1. Remove use_gpu / gpu_id / gpu_mem.
2. Select hardware with device='gpu', device='gpu:1' or device='cpu'.
3. If device is omitted, GPU 0 is used when Paddle sees a CUDA GPU, otherwise CPU.

# 2.x
ocr = PaddleOCR(use_gpu=True, lang='en')
# 3.x
ocr = PaddleOCR(device='gpu', lang='en')

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_common_args.py:38-50; paddlex-3.7.2/paddlex/utils/device.py:55-75; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1094-1111

Unknown argument: show_log#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

ValueError: Unknown argument: show_log

Cause. show_log was removed; 3.x uses a shared 'paddleocr' logger (default level ERROR).

1. Delete show_log=...
2. To change verbosity: import logging; from paddleocr import logger; logger.setLevel(logging.INFO)

import logging
from paddleocr import PaddleOCR, logger
logger.setLevel(logging.ERROR)  # replaces show_log=False
ocr = PaddleOCR(lang='en')

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:69; PaddleOCR/docs/version3.x/logging.en.md:9-24; PaddleOCR/paddleocr/_utils/logging.py:24-36

Unknown argument: use_onnx#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

ValueError: Unknown argument: use_onnx

Cause. use_onnx was replaced by high-performance inference (enable_hpi) and, from 3.5, by the engine/engine_config mechanism.

1. Remove use_onnx.
2. Either pass enable_hpi=True (high-performance inference plugin), or engine='onnxruntime' after pip install onnxruntime (CPU) / onnxruntime-gpu (CUDA 12).
3. ONNX Runtime options go in engine_config, e.g. engine_config={'providers': ['CUDAExecutionProvider']}.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:71; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:20-30,50-58,118-132

Unknown argument: drop_score#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

ValueError: Unknown argument: drop_score

Cause. drop_score is not in the 3.x deprecation map; the equivalent is text_rec_score_thresh (default 0.0 in 3.x vs 0.5 in 2.x).

1. Rename drop_score=0.5 to text_rec_score_thresh=0.5 (constructor or predict()).

ocr = PaddleOCR(text_rec_score_thresh=0.5)

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,90,191; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:107; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:45

Unknown argument: <other 2.x option>#

ValueError: Unknown argument: {name}

Cause. Only 11 old names are auto-mapped (use_angle_cls, det_model_dir, det_limit_side_len, det_limit_type, det_db_thresh, det_db_box_thresh, det_db_unclip_ratio, rec_model_dir, rec_batch_num, cls_model_dir, cls_batch_num), and only on PaddleOCR. Every other 2.x kwarg is rejected.

1. Look the name up in the migration table (migration.json).
2. rec_image_shape -> text_rec_input_shape; use_xpu/use_npu -> device='xpu'/'npu'; page_num/image_dir -> pass the file to predict().
3. Options with no 3.x equivalent must be deleted; advanced settings can be edited in an exported PaddleX config (export_paddlex_config_to_yaml, then paddlex_config=...).

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,155-169; PaddleOCR/paddleocr/_pipelines/base.py:74-100

Unknown argument on PPStructureV3 (layout / table / ocr / structure_version / det_model_dir ...)#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64. PPStructureV3(det_model_dir=...), (use_angle_cls=...) and (use_gpu=...) each raised Unknown argument.

ValueError: Unknown argument: table

Cause. PPStructureV3 has its own parameter set and no deprecated-name mapping (even det_model_dir / use_angle_cls fail here).

1. table -> use_table_recognition; formula -> use_formula_recognition (now default True); image_orientation -> use_doc_orientation_classify; layout_model_dir -> layout_detection_model_dir; table_model_dir -> wired_/wireless_table_structure_recognition_model_dir; det_model_dir -> text_detection_model_dir.
2. layout=False / ocr=False have no equivalent: use PaddleOCR for plain OCR or TableRecognitionPipelineV2 for tables.
3. recovery=True -> call res.save_to_word() / res.save_to_markdown() on each result.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:32-101,129-143

DeprecationWarning: The parameter `use_angle_cls` has been deprecated#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

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

Cause. A 2.x parameter name still works on PaddleOCR but is mapped to its 3.x name with a warning.

1. Rename to the name given in the warning (e.g. use_angle_cls -> use_textline_orientation, det_model_dir -> text_detection_model_dir, rec_batch_num -> text_recognition_batch_size).

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_utils/deprecation.py:36-42; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,156-159

`use_angle_cls` and `use_textline_orientation` are mutually exclusive#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive.

Cause. Both the deprecated name and its replacement were passed (CLI prints the same text with -- prefixes and exits with status 2).

1. Keep only the new name.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:163-166,595-600

The option `--use_angle_cls` has been deprecated#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

CLIDeprecationWarning: The option `--use_angle_cls` has been deprecated and will be removed in the future. Please refer to the documentation for more details.

Cause. Legacy 2.x flag used with paddleocr ocr.

1. Use the new flag: --use_textline_orientation, --text_detection_model_dir, --text_recognition_model_dir, --text_det_thresh, --text_det_box_thresh, --text_det_unclip_ratio, --text_det_limit_side_len, --text_det_limit_type, --text_recognition_batch_size, --textline_orientation_model_dir, --textline_orientation_batch_size.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_utils/deprecation.py:26-33; PaddleOCR/paddleocr/_pipelines/ocr.py:567-588

predict() got an unexpected keyword argument 'cls'#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

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

Cause. In 3.x, ocr() is a deprecated alias that forwards **kwargs to predict(), whose keyword-only signature has no cls/det/rec/bin/inv/alpha_color/slice. (Exact wording is generated by Python; Python < 3.10 omits the class name.)

1. ocr.ocr(img, cls=True) -> ocr.predict(img) with PaddleOCR(use_textline_orientation=True) or predict(img, use_textline_orientation=True).
2. det=False -> TextRecognition().predict(crops); rec=False -> TextDetection().predict(img).
3. bin/inv/alpha_color/slice have no predict() equivalent.

ocr = PaddleOCR(use_textline_orientation=True)
result = ocr.predict('img.png')

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:208-241; PaddleOCR/docs/update/upgrade_notes.en.md:69; paddleocr-2.10.0/paddleocr/paddleocr.py:696-706

DeprecationWarning: Please use `predict` instead.#

DeprecationWarning: Please use `predict` instead.

Cause. PaddleOCR.ocr() is decorated with typing_extensions.deprecated in 3.x.

1. Replace .ocr(img) with .predict(img).

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:239-241; PaddleOCR/paddleocr/_utils/deprecation.py:19

cannot import name 'draw_ocr' from 'paddleocr'#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

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

Cause. draw_ocr was a 2.x export; 3.x results draw themselves.

1. Remove the import.
2. Use res.save_to_img('output_dir') or res.img['ocr_res_img'] (a PIL Image).
3. Custom font: set env PADDLE_PDX_LOCAL_FONT_FILE_PATH=/path/to/font.ttf.

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en')
for res in ocr.predict('img.png'):
    res.save_to_img('output')
    img = res.img['ocr_res_img']  # PIL.Image

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; PaddleOCR/docs/update/upgrade_notes.en.md:38-48,65-66; PaddleOCR/docs/FAQ.en.md:195-197

cannot import name 'PPStructure' from 'paddleocr'#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

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

Cause. PPStructure was removed in 3.x.

1. pip install "paddleocr[doc-parser]"
2. from paddleocr import PPStructureV3
3. pipeline = PPStructureV3(); output = pipeline.predict('doc.png'); for res in output: res.save_to_markdown('out'); res.save_to_json('out')

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/docs/update/upgrade_notes.en.md:73; PaddleOCR/paddleocr/__init__.py:32-43; PaddleOCR/docs/version3.x/pipeline_usage/PP-StructureV3.en.md:963,1686-1700

cannot import name 'save_structure_res' / 'sorted_layout_boxes' / 'convert_info_docx'#

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

Cause. 2.x PP-Structure helper functions are not part of the 3.x package.

1. save_structure_res -> res.save_to_json / save_to_xlsx / save_to_html / save_to_img (or res.save_all).
2. convert_info_docx -> res.save_to_word(path).
3. convert_info_markdown / sorted_layout_boxes -> res.save_to_markdown(path), pipeline.concatenate_markdown_pages(...).
4. to_excel -> res.save_to_xlsx(path).
5. download_with_progressbar -> not needed; models auto-download.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:69,216,400,526,590,797

No module named 'paddleocr.tools' / 'paddleocr.ppocr' / 'paddleocr.ppstructure'#

ModuleNotFoundError: No module named 'paddleocr.tools'

Cause. The 2.x wheel shipped tools/, ppocr/, ppstructure/ and paddleocr.py inside the package; the 3.x package contains only paddleocr/ with a curated public API.

1. Import only from the top-level package: from paddleocr import PaddleOCR, PPStructureV3, TextDetection, ...
2. If you need 2.x internals, pin paddleocr==2.10.0 in a separate environment.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/pyproject.toml:61-64; PaddleOCR/paddleocr/__init__.py:84-131

KeyError: 0 / string indices when reading 3.x results with 2.x code#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64. result[0][0][1][0] raised KeyError: 0; the 2.x loop `for line in result[0]: box, (text, score) = line` walked the dict keys and raised ValueError: too many values to unpack (expected 2).

KeyError: 0

Cause. 3.x predict()/ocr() return a list of OCRResult objects (dict subclasses with keys like rec_texts, rec_scores, rec_polys), not [[box, (text, score)], ...]. result[0][0] looks up dict key 0. (The NoneType variant is the 2.x behaviour: 2.x returned None for an image with no text.)

1. Iterate results and read named fields: res['rec_texts'], res['rec_scores'], res['rec_polys'] (4x2 int16 arrays), res['rec_boxes'] ([x_min, y_min, x_max, y_max]).
2. Use res.json for a JSON-safe dict ({'res': {...}}).

for res in ocr.predict('img.png'):
    for text, score, poly in zip(res['rec_texts'], res['rec_scores'], res['rec_polys']):
        print(text, score, poly.tolist())

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/common/result/base_result.py:75; paddlex-3.7.2/paddlex/inference/pipelines/ocr/result.py:31; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:197-207; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1836-1853; paddleocr-2.10.0/paddleocr/paddleocr.py:762-772

Invalid OCR version#

ValueError: Invalid OCR version: PP-OCRv2. Supported values are ['PP-OCRv3', 'PP-OCRv4', 'PP-OCRv5', 'PP-OCRv6'].

Cause. 2.x accepted PP-OCR and PP-OCRv2. 3.x PaddleOCR accepts PP-OCRv3..PP-OCRv6; PPStructureV3 only PP-OCRv3..PP-OCRv5.

1. Use ocr_version='PP-OCRv5' or 'PP-OCRv6' (or omit it).
2. With PPStructureV3 do not pass 'PP-OCRv6'.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:58,97-100; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:28,103-106; paddleocr-2.10.0/paddleocr/paddleocr.py:91

paddleocr: error: argument COMMAND: invalid choice#

Reproduced by paddleocr.dev Reproduced by paddleocr.dev on 2026-10-27: paddleocr 3.7.0, paddlex 3.7.2, Python 3.13, Linux x86-64.

paddleocr: error: argument COMMAND: invalid choice: 'img.png' (choose from ...)

Cause. 2.x CLI syntax (paddleocr --image_dir x --use_angle_cls true) against the 3.x CLI, which requires a subcommand and uses -i/--input. Messages are produced by Python argparse (reproduced locally with a parser of the same shape on Python 3.13).

1. paddleocr ocr -i img.png --use_textline_orientation True
2. Structure: paddleocr pp_structurev3 -i doc.pdf --save_path out
3. Det only: paddleocr text_detection -i img.png; Rec only: paddleocr text_recognition -i crop.png
4. GPU/CPU: --device gpu:0 | --device cpu

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_cli.py:281-309; PaddleOCR/paddleocr/_utils/cli.py:31-45; PaddleOCR/paddleocr/_common_args.py:129-188

3.x results/speed differ from 2.x with the same image (no error)#

(behaviour change, no error)

Cause. Defaults changed: default models PP-OCRv6_medium (2.x: PP-OCRv4); doc orientation + UVDoc unwarping + textline orientation ON in the OCR pipeline YAML; det limit_side_len 64/min with max_side_limit 4000 (2.x 960/max); text_rec_score_thresh 0.0 (2.x drop_score 0.5); enable_mkldnn True (2.x False).

1. For 2.x-like behaviour: PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, text_rec_score_thresh=0.5).
2. Pin models with ocr_version='PP-OCRv4' (ch/en only) or explicit *_model_name.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-45; PaddleOCR/paddleocr/_pipelines/ocr.py:330-331; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:62-63,107,124,131; paddleocr-2.10.0/paddleocr/paddleocr.py:90; PaddleOCR/paddleocr/_constants.py:18; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1293-1298

Installation and dependencies#

Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.#

RuntimeError: Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.

Cause. engine='onnxruntime' / 'transformers' / enable_hpi selected without the runtime installed; for GPU ONNX the CUDAExecutionProvider must be present (onnxruntime engine supports only cpu and gpu).

1. pip install onnxruntime (CPU) or onnxruntime-gpu (NVIDIA, CUDA 12.x).
2. Transformers engine: pip install "transformers>=5.10.0" plus its backend.
3. HPI: paddleocr install_hpi_deps cpu|gpu|npu.
4. Install only one inference engine per environment.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/models/engines/onnxruntime.py:59-82; paddlex-3.7.2/paddlex/inference/models/engines/transformers.py:73-77; paddlex-3.7.2/paddlex/inference/models/engines/hpi.py:66-70; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:32-58; PaddleOCR/paddleocr/_cli.py:96-107

pip cannot find paddlepaddle-gpu 3.x (No matching distribution found)#

ERROR: No matching distribution found for paddlepaddle-gpu==3.2.0

Cause. paddlepaddle-gpu on PyPI stops at 2.6.2 (checked pypi.org JSON); 3.x GPU wheels are served from PaddlePaddle's own index. Plain pip install paddlepaddle-gpu from PyPI installs 2.6.2, which does not meet PaddleOCR 3.x's PaddlePaddle >= 3.0.0 requirement. CPU paddlepaddle 3.3.1 on PyPI only has wheels for CPython 3.9-3.13 on manylinux x86_64, Windows amd64 and macOS arm64.

1. Use the official index URL: python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ (or cu118 for older drivers).
2. Use Python 3.9-3.13.
3. Pick the wheel by GPU driver version, not by local CUDA toolkit version.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: https://pypi.org/pypi/paddlepaddle-gpu/json (latest 2.6.2, fetched 2026-10-27); https://pypi.org/pypi/paddlepaddle/3.3.1/json; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:54-65; PaddleOCR/docs/version3.x/paddleocr_and_paddlex.en.md:27-39

No module named 'pyclipper' / 'shapely' / 'cv2'#

ModuleNotFoundError: No module named 'pyclipper'

Cause. pyclipper, shapely, opencv-contrib-python, pypdfium2 and python-bidi come from paddlex[ocr-core], which paddleocr depends on. They go missing after installing with --no-deps (which the repo FAQ suggests for conflicts) or after manual uninstalls.

1. pip install --force-reinstall "paddleocr" (without --no-deps), or pip install "paddlex[ocr-core]>=3.7.0,<3.8.0".
2. Use a fresh virtual environment.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2.dist-info/METADATA:101-106; PaddleOCR/pyproject.toml:49-55; PaddleOCR/docs/FAQ.en.md:15-20

NumPy 2 / numpy version conflicts#

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.x.x as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.

Cause. paddlex 3.7.2 requires numpy>=1.24,<2.4 (paddlepaddle 3.3.1 requires numpy>=1.21), so NumPy 2.0-2.3 is supported in 3.x. Errors come from (a) a numpy >= 2.4 forced into the env, or (b) an extension compiled against NumPy 1.x (e.g. in an old 2.x-era environment) running on NumPy 2. The NumPy text comes from NumPy itself.

1. pip install "numpy>=1.24,<2.4"
2. Upgrade the package that the traceback names (or downgrade numpy to <2 if staying on an old 2.x stack).
3. Prefer a fresh environment when moving from paddleocr 2.x to 3.x.

Applies to: paddleocr 3.x environments; old paddleocr 2.x environments upgraded to NumPy 2. Source: paddlex-3.7.2.dist-info/METADATA:35; https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist); numpy v2.0.0 numpy/core/_multiarray_umath.py:23-29 and numpy/__init__.py:395-399 (raw.githubusercontent.com/numpy/numpy/v2.0.0)

protobuf errors when importing paddle#

(varies; e.g. 'TypeError: Descriptors cannot be created directly.')

Cause. paddlepaddle 3.2.2 and 3.3.1 declare protobuf>=3.20.2; an older protobuf pinned by another package conflicts.

1. pip install --upgrade "protobuf>=3.20.2"
2. Install PaddleOCR in its own virtual environment.

Applies to: paddlepaddle 3.x. Source: https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist: protobuf>=3.20.2); https://pypi.org/pypi/paddlepaddle/3.2.2/json

Apple Silicon (M1-M4): which install works#

(no single error string)

Cause. paddlepaddle publishes macOS arm64 CPU wheels on PyPI (cp39-cp313). The official PaddleOCR-VL Apple Silicon guide installs paddlepaddle==3.2.1 from the CPU index and requires >= 3.2.1; Docker is not supported there; the PaddlePaddle engine is the only local engine on that hardware. There is no CUDA, so use device='cpu'.

1. python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
2. python -m pip install -U "paddleocr[doc-parser]" (or plain paddleocr for OCR only)
3. Run with device='cpu'.

Applies to: macOS on Apple Silicon. Source: PaddleOCR/docs/version3.x/pipeline_usage/PaddleOCR-VL-Apple-Silicon.en.md:31-60; https://pypi.org/pypi/paddlepaddle/3.3.1/json (macosx_11_0_arm64 wheels)

[W:onnxruntime ... Removing initializer ...] warnings#

Reproduced by paddleocr.dev Tested by paddleocr.dev on 2026-10-27: paddleocr 3.7.0 + onnxruntime 1.31.1, no PaddlePaddle installed.

[W:onnxruntime:...] ... Removing initializer ...

Cause. With engine='onnxruntime', ONNX Runtime prints many 'Removing initializer' warnings when the models load. In our test they were harmless: paddleocr 3.7.0 with only onnxruntime 1.31.1 installed (no PaddlePaddle) returned correct results.

1. Ignore them. They appeared on first load and did not change the output.
2. To run without PaddlePaddle at all: pip install paddleocr onnxruntime, then PaddleOCR(engine='onnxruntime').

# pip install paddleocr onnxruntime
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', engine='onnxruntime')

Applies to: paddleocr 3.5+ with engine='onnxruntime'. Source: tested by paddleocr.dev 2026-10-27 (paddleocr 3.7.0, onnxruntime 1.31.1); PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:50-58

CPU, speed and engines#

Invalid precision / Invalid engine#

ValueError: Invalid precision: int8. Supported values are: ['fp32', 'fp16'].

Cause. precision only accepts fp32/fp16; engine only None, paddle, paddle_static, paddle_dynamic, transformers, onnxruntime.

1. Use precision='fp16' with use_tensorrt=True, or omit it.
2. Use one of the listed engine values.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_common_args.py:29-35,58-69; PaddleOCR/paddleocr/_constants.py:21

MKL-DNN is not available#

ValueError: MKL-DNN is not available

Cause. run_mode 'mkldnn' explicitly requested (e.g. engine_config={'run_mode': 'mkldnn'}) on a Paddle build/CPU without MKL-DNN. The related warning "The model(X) is not supported to run in MKLDNN mode! Using paddle instead!" is informational (model in PaddleX's MKLDNN blocklist, e.g. SLANet, UVDoc, PP-FormulaNet).

1. Use run_mode 'paddle' or omit run_mode; with enable_mkldnn (default True) PaddleX only picks mkldnn when available.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/pp_option.py:31-43,161-170; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:317-327; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/blocklists.py:46

engine_config cannot mix per-engine bucket keys with flat config keys#

ValueError: engine_config cannot mix per-engine bucket keys with flat config keys. Use either a flat dict for the resolved engine only, or a dict whose top-level keys are exclusively inference engine names. Flat-like keys: [...]; bucket-like keys: [...].

Cause. engine_config mixed {'paddle_static': {...}} with flat keys like 'run_mode'.

1. Use a flat dict for the selected engine (engine='paddle_static', engine_config={'run_mode': 'paddle', 'cpu_threads': 4}) or only engine-name buckets.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/models/__init__.py:176-213; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:134-141

PaddleOCR is slow on CPU#

Reproduced by paddleocr.dev Measured by paddleocr.dev on 2026-10-27 (4-vCPU Intel Xeon @ 2.10 GHz, no GPU).

(no error: each page takes several seconds)

Cause. The default 3.x OCR pipeline runs PP-OCRv6_medium plus three helper models that are on by default: document orientation, UVDoc unwarping and text-line orientation. On CPU, PaddlePaddle is fastest through oneDNN (enable_mkldnn=True, the default). In our benchmark (helper models off) PP-OCRv6_medium averaged 4.51 s per page on PaddlePaddle 3.2.0 and 2.92 s on ONNX Runtime; PP-OCRv6_small 1.23 s / 0.90 s; PP-OCRv6_tiny 0.39 s / 0.26 s. With enable_mkldnn=False (PaddlePaddle 3.3.1) medium took 11.88 s.

1. For upright, flat scans turn the helper models off: PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False).
2. Try engine='onnxruntime' after pip install onnxruntime: fastest for PP-OCRv6 in our test. Exception: PP-OCRv5_server was much slower on ONNX Runtime (35.70 s vs 5.25 s per page).
3. Use a smaller model: text_detection_model_name='PP-OCRv6_small_det', text_recognition_model_name='PP-OCRv6_small_rec' (or the _tiny pair).
4. Keep enable_mkldnn=True and pin paddlepaddle==3.2.0 rather than disabling oneDNN to avoid the 3.3.x crash.
5. Create the PaddleOCR object once and reuse it. The first predict() is slower (receipt: 4.88 s first run, 3.23 s median of three in our test).

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    text_detection_model_name='PP-OCRv6_small_det',
    text_recognition_model_name='PP-OCRv6_small_rec',
    engine='onnxruntime',  # pip install onnxruntime
)

Applies to: paddleocr 3.x on CPU. Source: paddleocr.dev benchmark: _src/data/bench/summary.json, results.jsonl (2026-10-27); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13; PaddleOCR/paddleocr/_constants.py:18

GPU#

AssertionError when device='cuda' (or other invalid device strings)#

AssertionError (from paddlex/utils/device.py parse_device)

Cause. PaddleX accepts device types cpu, gpu, xpu, npu, mlu, gcu, dcu, iluvatar_gpu, metax_gpu. 'cuda', 'cuda:0' or 'mps' are rejected by a bare assert; 'cpu:0' raises 'No Device ID should be specified for CPUs'.

1. Use device='gpu' or 'gpu:0' (not 'cuda').
2. Use device='cpu' (no index).

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/utils/device.py:31-41,78-100

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly#

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly. (error code is ...)
  Suggestions:
  1. Check if the third-party dynamic library (e.g. CUDA, CUDNN) is installed correctly and its version is matched with paddlepaddle you installed.
  2. Configure third-party dynamic library environment variables as follows:
  - Linux: set LD_LIBRARY_PATH by `export LD_LIBRARY_PATH=...`

Cause. paddlepaddle-gpu could not dlopen CUDA/cuDNN libraries of the version it was built for.

1. Install the paddlepaddle-gpu build that matches your driver (cu118 needs driver >= 450.80.02; cu126 needs >= 550.54.14).
2. Or use the official Docker images paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6 / paddle:3.0.0-gpu-cuda12.6-cudnn9.5-trt10.5.
3. If libraries exist but are not found, add their directory to LD_LIBRARY_PATH (Linux) / PATH (Windows).

Applies to: paddlepaddle-gpu 3.x (any paddleocr 3.x). Source: Paddle v3.3.1 paddle/phi/backends/dynload/dynamic_loader.cc:386-400; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:16-28,58-65

Out of memory error on GPU 0 (ResourceExhaustedError)#

ResourceExhaustedError: 

Out of memory error on GPU 0. Cannot allocate ... memory on GPU 0, ... memory has been allocated(actual using allocated memory ...) and available memory is only ....

Please check whether there is any other process using GPU 0.
1. If yes, please stop them, or start PaddlePaddle on another GPU.
2. If no, please decrease the batch size of your model.

Cause. GPU memory exhausted (large images, big batch, server-size models, or other processes on the GPU).

1. Free the GPU or pick another one: device='gpu:1'.
2. Lower batch sizes: text_recognition_batch_size=1, textline_orientation_batch_size=1.
3. Lower detection resolution: text_det_limit_side_len / text_det_limit_type, or reduce max_side_limit in an exported config.
4. Use mobile models, e.g. text_detection_model_name='PP-OCRv5_mobile_det', text_recognition_model_name='PP-OCRv5_mobile_rec'.
5. Disable unneeded sub-models (use_doc_orientation_classify=False, use_doc_unwarping=False).
6. Note: the repo FAQ also lists gpu_mem / batch_size / enable_memory_optim / det_limit_side_len; in 3.x those are not PaddleOCR constructor args (gpu_mem etc. raise 'Unknown argument').

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: Paddle v3.3.1 paddle/phi/core/memory/allocation/cuda_allocator.cc:75-83; PaddleOCR/docs/FAQ.en.md:85-92; PaddleOCR/paddleocr/_pipelines/ocr.py:73-92; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:796

NVIDIA RTX 50-series GPU on Windows does not work with standard paddlepaddle-gpu#

(no single error string documented)

Cause. Official docs: PaddlePaddle installed the standard way does not properly support NVIDIA 50-series GPUs on Windows; special CUDA 12.9 wheels are provided (training of text recognition still has known issues).

1. Install the dedicated wheel for your Python version listed in paddlepaddle_installation (paddlepaddle_gpu-3.0.0.dev20250717-cp3XX-cp3XX-win_amd64.whl).

Applies to: Windows + NVIDIA RTX 50-series. Source: PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:79-97

Models and languages#

No models are available for lang=... and ocr_version=...#

ValueError: No models are available for lang='latin' and ocr_version=None.

Cause. The lang/ocr_version combination has no model. Common migration case: 2.x script-group codes ('latin', 'arabic', 'cyrillic', 'devanagari', 'ch_doc', 'structure') are not accepted as lang in 3.x; also PP-OCRv4 only supports 'ch' and 'en', and PP-OCRv6 only ch/chinese_cht/en/japan + Latin languages. PPStructureV3 words it: "No models are available for the language 'xx' and OCR version 'yy'."

1. Use an actual language code (e.g. 'fr', 'de', 'es', 'ru', 'ar', 'hi', 'korean', 'japan').
2. Drop ocr_version to let PaddleOCR pick the newest version that supports the language.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:58-62,113-119,318-422; PaddleOCR/paddleocr/_utils/langs.py; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:119-125; paddleocr-2.10.0/paddleocr/paddleocr.py:506-527

`lang` and `ocr_version` will be ignored when model names or model directories are not `None`.#

UserWarning: `lang` and `ocr_version` will be ignored when model names or model directories are not `None`.

Cause. You passed lang/ocr_version together with text_detection_model_*/text_recognition_model_* (or the deprecated det_model_dir/rec_model_dir).

1. Choose models either by lang/ocr_version or by explicit model names/dirs, not both.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: PaddleOCR/paddleocr/_pipelines/ocr.py:122-127

Model name mismatch: expected 'PP-OCRv6_medium_det' but config has ...#

ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir.

Cause. A *_model_dir was given without the matching *_model_name, so the pipeline keeps its default model name (PP-OCRv6_medium_det / PP-OCRv6_medium_rec in the OCR YAML) and PaddleX compares it with Global.model_name in the directory's inference.yml.

1. Pass the model name that matches the directory, e.g. text_detection_model_name='PP-OCRv5_server_det', text_detection_model_dir='./PP-OCRv5_server_det_infer'.
2. Use 3.x-format inference model directories (they contain inference.yml).

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

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/models/utils/model_resolver.py:25-44; paddlex-3.7.2/paddlex/inference/models/utils/model_config.py:24-31; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:27,42; PaddleOCR/paddleocr/_pipelines/utils.py:14-27

No model hoster is available / No available model hosting platforms detected#

Exception: No available model hosting platforms detected. Please check your network connection.

Cause. PaddleX downloads official models on first use from HuggingFace (default), AIStudio, ModelScope or BOS, after a connectivity check. Firewalls/proxies or offline hosts make every hoster fail.

1. Set the preferred source before importing paddleocr: os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos' (values: huggingface, modelscope, aistudio, bos; case-insensitive).
2. Skip the slow connectivity check: PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK=True.
3. Custom HF mirror: PADDLE_PDX_HUGGING_FACE_ENDPOINT=https://...
4. Offline: copy models into ~/.paddlex/official_models/<model_name> (cache root PADDLE_PDX_CACHE_HOME) or pass *_model_dir together with matching *_model_name.

import os
os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos'
os.environ['PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK'] = 'True'
from paddleocr import PaddleOCR

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/utils/official_models.py:878-921,962-967,1015-1041; paddlex-3.7.2/paddlex/utils/flags.py:72-79; paddlex-3.7.2/paddlex/utils/cache.py:28-29; PaddleOCR/docs/FAQ.en.md:29-34,55-60

No valid model files were found for engine 'paddle_static' / No valid PaddlePaddle model found#

ValueError: No valid model files were found for engine 'paddle_static'.

Cause. The model directory lacks inference.json or inference.pdmodel together with inference.pdiparams (or the format needed by the chosen engine, e.g. inference.onnx for onnxruntime).

1. Point *_model_dir at an exported inference model folder (inference.json/.pdmodel + inference.pdiparams + inference.yml).
2. Delete a partially downloaded folder under ~/.paddlex/official_models/ to force re-download.

Applies to: paddleocr 3.x (verified against repo commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2). Source: paddlex-3.7.2/paddlex/inference/models/engines/_base.py:107-115; paddlex-3.7.2/paddlex/inference/models/utils/model_paths.py:50-76; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:345-347; paddlex-3.7.2/paddlex/inference/utils/official_models.py:944-946

Results#

Empty result: rec_texts is []#

{'rec_texts': [], 'rec_scores': [], ...}   (2.x returned [None])

Cause. 3.x never returns None. An image with no accepted text gives an OCRResult whose rec_texts, rec_scores and rec_polys are empty lists (2.x appended None instead). Text can be lost at detection (text_det_thresh 0.3, text_det_box_thresh 0.6 by default) or at the score filter text_rec_score_thresh: rec_* only keep lines scoring at or above it, while dt_polys keeps every detected box.

1. Print res['dt_polys']. Empty means detection found nothing; boxes there but an empty rec_texts means the score filter removed everything.
2. Detection: lower text_det_box_thresh (for example 0.4) and/or text_det_thresh for faint or low-contrast text.
3. Score filter: the 3.x default is 0.0. A value carried over from 2.x drop_score (0.5) hides low-confidence lines.
4. Set lang to the document's language. The default PP-OCRv6 models cover Chinese, English, Japanese and Latin-script languages.
5. Replace 2.x checks like if result[0] is None with if not result[0]['rec_texts'].

res = ocr.predict('page.png')[0]
print(len(res['dt_polys']), 'boxes detected')
print(res['rec_texts'])
# faint text:
res = ocr.predict('page.png', text_det_box_thresh=0.4, text_rec_score_thresh=0.0)[0]

Applies to: paddleocr 3.x. Source: paddleocr-2.10.0/paddleocr/paddleocr.py:762-772; paddlex-3.7.2/paddlex/inference/pipelines/ocr/pipeline.py:480-498; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:32-45; PaddleOCR/paddleocr/_pipelines/ocr.py:58-62

Boxes don't line up with the original image#

Reproduced by paddleocr.dev Tested by paddleocr.dev on 2026-10-27: paddleocr 3.7.0 + paddlepaddle 3.2.0.

(no error: rec_polys / rec_boxes look shifted when drawn on your own copy of the image)

Cause. The default PaddleOCR() has use_doc_unwarping=True. UVDoc unwarps the page first, and the boxes are in the coordinates of that processed image, not your original. 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. Document orientation correction (also on by default) can rotate the page too.

1. For coordinates on the original image: PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False).
2. Or use the pictures PaddleOCR draws itself: res.save_to_img('out') writes both ocr_res_img and preprocessed_img (res.img has the same two keys).

ocr = PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False)
res = ocr.predict('receipt.png')[0]
print(res['rec_polys'][0])

Applies to: paddleocr 3.x OCR pipeline with default settings. Source: tested by paddleocr.dev 2026-10-27 (paddleocr 3.7.0 + paddlepaddle 3.2.0); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13

Questions#