This document provides comprehensive guidance for migrating code from PaddleOCR 2.x to PaddleOCR 3.x. It covers the major architectural changes, API modifications, pipeline renames, and dependency updates that affect compatibility. Users currently running PaddleOCR 2.x should consult this guide before upgrading to understand breaking changes and required code modifications.
For information about the new features and capabilities in PaddleOCR 3.x, see System Architecture and Major Pipelines. For installation instructions, see Installation and Environment Setup.
PaddleOCR 3.x represents a fundamental architectural redesign driven by four years of rapid feature expansion since the 2.0 release in February 2021. The 2.x series began with a lightweight-centric architecture but accumulated significant technical debt as new capabilities (multilingual recognition, layout analysis, document understanding) were added incrementally.
Key motivations for the 3.x upgrade:
| Challenge in 2.x | Solution in 3.x |
|---|---|
| Code duplication and inconsistent interfaces across modules | Modular, plugin-based architecture with unified interfaces |
| Legacy dependencies incompatible with PaddlePaddle 3.0+ | Full compatibility with PaddlePaddle 3.0's CINN compiler and new features |
| Limited integration with vision-language models | Native integration with VLMs (PaddleOCR-VL, PP-ChatOCRv4) |
| Fragmented deployment capabilities | Unified deployment framework through PaddleX integration |
| High maintenance burden from "bridging" layers | Clean separation between user API and underlying capabilities |
Sources: README.md83-84 docs/update/upgrade_notes.md1-14 docs/update/upgrade_notes.en.md1-14
The following diagram illustrates the fundamental architectural shift from PaddleOCR 2.x to 3.x:
PaddleOCR 2.x vs 3.x Architecture Comparison
Key architectural changes:
PaddleXPipelineWrapper, providing consistent behavior across different tasksSources: README.md77-81 docs/version3.x/paddleocr_and_paddlex.md13-22 docs/update/upgrade_notes.md15-22
PaddleOCR 3.x introduces strict version dependencies between three components: PaddleOCR, PaddleX, and PaddlePaddle framework. The following table shows the compatibility requirements:
| PaddleOCR Version | PaddleX Version | PaddlePaddle Version | Notes |
|---|---|---|---|
3.0.0 | 3.0.0 | >= 3.0.0 | Initial 3.x release |
3.0.1 | 3.0.1 | >= 3.0.0 | Bug fixes |
3.0.2 | 3.0.2 | >= 3.0.0 | Performance improvements |
3.0.3 | >= 3.0.3 | >= 3.0.0 | Relaxed PaddleX constraint |
3.1.x | >= 3.1.0, < 3.2.0 | >= 3.0.0 | MCP server, multilingual |
3.2.x | >= 3.2.0, < 3.3.0 | >= 3.0.0 | C++ deployment, benchmarks |
3.3.x | >= 3.3.0, < 3.4.0 | >= 3.0.0 | PaddleOCR-VL |
3.4.x | >= 3.4.0, < 3.5.0 | >= 3.0.0 | PaddleOCR-VL-1.5 |
Dependency Installation:
The PaddleX dependency is automatically installed when installing PaddleOCR. Note that only OCR-related dependencies are installed by default (~738 MB total), not all PaddleX capabilities.
Sources: docs/version3.x/paddleocr_and_paddlex.md25-36 docs/quick_start.en.md9-26 pyproject.toml41-46
PaddleOCR 2.x to 3.x API Comparison
Key changes in the PaddleOCR class:
lang, use_angle_cls, use_gpu still work as expecteduse_doc_orientation_classify: Document orientation classification (replaces use_angle_cls for document-level rotation)use_doc_unwarping: Text image unwarping preprocessinguse_textline_orientation: Text line orientation classificationpaddlex_config: Path to PaddleX configuration file or config dictionaryocr() method parameters: det, rec, cls - use separate classes insteadpredict() method: Returns result objects instead of nested listsMigration example:
Sources: docs/update/upgrade_notes.md26-68 docs/quick_start.en.md63-111 docs/update/upgrade_notes.en.md25-67
PaddleOCR 3.x Result Structure
3.x result object structure:
Sources: docs/quick_start.en.md89-111 docs/quick_start.md87-109
Features removed in 3.x:
| 2.x Feature | 3.x Replacement | Migration Path |
|---|---|---|
ocr.ocr(det=False) | TextDetection class | Use from paddleocr import TextDetection |
ocr.ocr(rec=False) | TextRecognition class | Use from paddleocr import TextRecognition |
PPStructure class | PPStructureV3 class | Update class name and consult new API docs |
use_onnx parameter | High-performance inference | Use enable_hpi=True or configure via PaddleX config |
show_log parameter | New logging system | Import and configure paddleocr._utils.logging.logger |
draw_ocr() function | Result.save_to_img() | Call method on result object |
Example migrations:
Sources: docs/update/upgrade_notes.md69-73 docs/update/upgrade_notes.en.md68-72
The show_log parameter in 2.x had a design flaw: all PaddleOCR instances shared a single global logger, causing cross-instance interference. PaddleOCR 3.x introduces a new logging system:
Sources: docs/update/upgrade_notes.md69
PaddleOCR 3.x introduces new pipeline names aligned with PaddleX conventions. The following diagram shows the evolution:
Pipeline Evolution from 2.x to 3.x
Detailed mapping table:
| 2.x Pipeline | 3.x Pipeline | PaddleX Registration Name | Primary Use Case |
|---|---|---|---|
PaddleOCR | PaddleOCR (PP-OCRv5) | OCR | General text detection + recognition |
| N/A | TextDetection | Part of OCR | Text detection only |
| N/A | TextRecognition | Part of OCR | Text recognition only |
PPStructure | PPStructureV3 | PP-StructureV3 | Document layout + multi-element parsing |
| N/A | PPChatOCRv4Doc | PP-ChatOCRv4-doc | Intelligent info extraction with LLM |
| N/A | PaddleOCRVL | PaddleOCR-VL, PaddleOCR-VL-1.5 | VLM-based document parsing |
| N/A | TableRecognitionPipelineV2 | table_recognition_v2 | Table structure recognition |
| N/A | SealRecognition | seal_recognition | Seal/stamp text recognition |
| N/A | FormulaRecognitionPipeline | formula_recognition | Mathematical formula recognition |
| N/A | PPDocTranslation | PP-DocTranslation | Document translation |
Model version selection:
The PaddleOCR class in 3.x defaults to PP-OCRv5 models but supports backward compatibility:
Sources: docs/version3.x/paddleocr_and_paddlex.md38-51 paddleocr/_pipelines/pp_structurev3.py25
PaddleOCR 3.x introduces a hierarchical configuration system through PaddleX integration:
Configuration Flow Diagram
Or via CLI:
Python API:
CLI:
PaddleOCR parameters are mapped to PaddleX's nested structure via the STRUCTURE dictionary pattern found in each pipeline implementation:
This allows PaddleOCR's simplified parameter names to map to PaddleX's deeply nested configuration structure.
Sources: docs/version3.x/paddleocr_and_paddlex.md53-97 paddleocr/_pipelines/pp_structurev3.py304-337
pyproject.toml dependency specification:
The modular dependency system ensures that installing PaddleOCR doesn't pull in all of PaddleX's dependencies—only those needed for the selected features.
Sources: pyproject.toml41-61 docs/version3.x/paddleocr_and_paddlex.md23
Checklist for migration planning:
Step 1: Update installation
Step 2: Update imports and initialization
Step 3: Update inference calls
Step 4: Update visualization
Sources: docs/update/upgrade_notes.md26-73 docs/quick_start.en.md63-197
PaddleOCR 3.x continues to evolve. The following limitations are known as of version 3.4.x:
| Feature | Status | Workaround |
|---|---|---|
| C++ local deployment | Partial support (Linux/Windows only for select models) | Use Python deployment or wait for updates |
| High-throughput service deployment | Basic support available, not performance-parity with PaddleServing | Use Docker-based deployment, monitor for updates |
| Mobile/edge deployment | Limited to key models (PP-OCRv5, select modules) | Check model compatibility before deployment |
For issues during migration:
Sources: docs/update/upgrade_notes.md75-83 docs/update/upgrade_notes.en.md74-82 README.md148-222
Major changes:
Breaking changes:
PPStructure completely replaced by PPStructureV3New features:
Additional changes:
New features:
Configuration changes:
enable_mkldnn parameter behavior clarifiedNew features:
Model changes:
PaddleOCRVL classSources: README.md85-237
Summary: PaddleOCR 3.x represents a major architectural evolution requiring careful migration planning. The core workflow remains conceptually similar, but implementation details have changed significantly to support modular design, VLM integration, and PaddlePaddle 3.0 features. Most migration effort involves updating API calls, result handling, and logging configuration. The new architecture provides cleaner abstractions and better extensibility for future enhancements.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.