# How to Use PaddleOCR for End-to-End OCR: Complete Python and CLI Guide

> Master end-to-end OCR with PaddleOCR in Python and CLI. Detect and recognize text efficiently using the PaddleOCR class for structured results and visualization. Get started now.

- Repository: [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Use the `PaddleOCR` class to instantiate a PaddleX pipeline that performs text detection and recognition in a single inference call, returning structured results with built-in visualization methods.**

PaddleOCR is an open-source optical character recognition system maintained by the PaddlePaddle community. To use PaddleOCR for end-to-end OCR, developers initialize a high-level wrapper that automatically configures detection, recognition, and post-processing models. This pipeline architecture abstracts hardware-specific optimizations while exposing a unified interface for both Python scripting and command-line batch processing.

## Quick Start with the Python API

The fastest way to run end-to-end OCR is through the `PaddleOCR` class defined in **[`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py)**. This class inherits from `PaddleXPipelineWrapper` (**[`paddleocr/_pipelines/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/base.py)**) and handles all model initialization internally.

```python
from paddleocr import PaddleOCR

# Initialize with default models (PP-OCRv5, English/Chinese mixed)

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
)

# Run inference on a local image or URL

results = ocr.predict("docs/example.png")

# Handle outputs

for line in results:
    line.print()           # Console output: text, confidence, bbox

    line.save_to_img("vis")    # Visualize bounding boxes

    line.save_to_json("out")   # Export structured JSON

```

During instantiation, the constructor builds a `_params` dictionary and calls `load_pipeline_config("OCR")` to fetch default PaddleX configurations. User overrides are merged via `_get_paddlex_config_overrides` before `create_pipeline` initializes the actual inference engine.

## Internal Architecture and Data Flow

Understanding the internal flow helps debug configuration issues and optimize performance. The end-to-end pipeline follows this execution path:

1. **API Entry**: `PaddleOCR.__init__` (lines 54-70 in **[`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py)**) collects model arguments and normalizes deprecated parameters (lines 71-144).

2. **Wrapper Initialization**: The base class `PaddleXPipelineWrapper` (lines 54-71 in **[`paddleocr/_pipelines/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/base.py)**) loads the default OCR pipeline configuration.

3. **Config Merging**: User-provided dictionaries are deep-merged with defaults using `_get_merged_paddlex_config` and `_merge_dicts` (lines 90-101).

4. **Pipeline Creation**: The system calls `create_pipeline` (lines 102-106) to instantiate the hardware-specific inference engine.

5. **Inference**: `PaddleOCR.predict` (lines 98-104) forwards inputs directly to `self.paddlex_pipeline.predict`, which executes detection and recognition sequentially.

6. **Result Handling**: Output objects expose `print()`, `save_to_img()`, and `save_to_json()` methods for immediate consumption.

Hardware selection (CPU, GPU, XPU, NPU) occurs automatically based on the installed PaddlePaddle runtime and the optional `device` argument defined in **[`paddleocr/_common_args.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_common_args.py)**.

## Command-Line Interface for Batch Processing

For production workflows or shell scripting, PaddleOCR exposes the same functionality through a CLI implemented in **[`paddleocr/_utils/cli.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_utils/cli.py)**. The interface uses `add_simple_inference_args` to parse arguments and `perform_simple_inference` to execute the pipeline.

```bash
paddleocr ocr -i https://github.com/PaddlePaddle/PaddleOCR/raw/main/docs/images/ocr_demo.png \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False

```

CLI arguments map directly to the Python API parameters, ensuring consistent behavior across interfaces.

## Customizing Models and Languages

To use PaddleOCR for end-to-end OCR with non-default languages or specific model versions, override the `lang` and `ocr_version` parameters. The private method `_get_ocr_model_names` resolves these arguments to specific checkpoint files from the PaddleOCR model zoo.

```python
from paddleocr import PaddleOCR

# Configure for Korean text recognition using PP-OCRv5

ocr = PaddleOCR(
    lang="ko",
    ocr_version="PP-OCRv5",
)

result = ocr.predict("korean_sample.jpg")

```

Available options for `lang` include standard language codes (e.g., `"en"`, `"ch"`, `"fr"`, `"german"`), while `ocr_version` selects between model generations like `"PP-OCRv4"` and `"PP-OCRv5"`.

## Processing Results Programmatically

Result objects returned by `predict()` behave like iterables containing dictionaries with `text`, `score`, and `bbox` keys. Extract pure text strings for downstream natural language processing or retrieval-augmented generation (RAG) pipelines:

```python

# Concatenate all detected text lines

full_text = "\n".join([line["text"] for line in result])
print("Extracted content:\n", full_text)

```

Each result object maintains metadata about the source image and detection coordinates, enabling precise mapping between recognized text and original document regions.

## Summary

- **Primary Entry Point**: The `PaddleOCR` class in **[`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py)** provides the main user interface for end-to-end OCR.
- **Pipeline Architecture**: Internally wraps PaddleX pipelines via `PaddleXPipelineWrapper` (**[`paddleocr/_pipelines/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/base.py)**), handling model loading and hardware abstraction.
- **Flexible Interfaces**: Supports both Python API and CLI (**[`paddleocr/_utils/cli.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_utils/cli.py)**) with identical parameter sets.
- **Rich Outputs**: Result objects include `print()`, `save_to_img()`, and `save_to_json()` methods for immediate visualization and data export.
- **Multi-Language Support**: Configure via `lang` parameter with automatic model resolution for 80+ languages.

## Frequently Asked Questions

### What hardware accelerators does PaddleOCR support?

PaddleOCR automatically detects and utilizes available hardware including NVIDIA GPUs, Intel CPUs with MKLDNN optimization, Baidu XPU, and Huawei NPU. Specify the target device explicitly using the `device` argument (e.g., `device="gpu:0"`) or allow auto-detection based on your PaddlePaddle installation.

### How do I disable document preprocessing steps?

Set `use_doc_orientation_classify=False` to skip document-level rotation detection, `use_doc_unwarping=False` to disable geometric distortion correction, and `use_textline_orientation=False` to turn off line-level orientation classification. These parameters reduce latency when processing pre-aligned images.

### Can I use custom-trained models instead of the defaults?

Yes. While the standard API downloads official PP-OCR models, you can pass a custom pipeline configuration YAML to the underlying PaddleX pipeline. Use the utilities in **[`paddleocr/_pipelines/utils.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/utils.py)** to generate valid config structures from custom training outputs.

### What is the difference between PP-OCRv4 and PP-OCRv5?

`PP-OCRv5` represents the latest model generation with improved accuracy for multilingual text and curved line detection. Specify `ocr_version="PP-OCRv5"` during initialization to access newer architectures, or use `"PP-OCRv4"` for legacy compatibility with existing deployments.