# How to Use PaddleOCR for Text Detection: CLI and Python API Guide

> Master PaddleOCR text detection with our CLI and Python API guide. Learn to load models, preprocess images, and get accurate bounding boxes. Get started today!

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

---

**PaddleOCR performs text detection by loading a pre-trained inference model, preprocessing images according to size constraints, running neural network inference, and post-processing results to return bounding box coordinates with confidence scores.**

PaddleOCR is an open-source optical character recognition framework maintained by Baidu's PaddlePaddle team. To use PaddleOCR for text detection, you can invoke the `TextDetection` class directly through Python or execute the `text_detection` CLI subcommand. This article explores the modular pipeline architecture, essential tuning parameters, and practical code implementations based on the source code in the PaddlePaddle/PaddleOCR repository.

## Core Architecture of the Detection Pipeline

PaddleOCR follows a modular design where **text detection** operates as a distinct stage from recognition. The detection component locates text-line bounding boxes and outputs their coordinates together with confidence scores.

### Pipeline Components

| Component | Description | Source File |
|-----------|-------------|-------------|
| **User-Facing Wrapper** | `TextDetection` inherits from `TextDetectionMixin` (argument handling) and `PaddleXPredictorWrapper` (model loading). | [`paddleocr/_models/text_detection.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/text_detection.py) |
| **Argument Mixin** | `TextDetectionMixin` stores hyper-parameters including `limit_side_len`, `thresh`, `box_thresh`, `unclip_ratio`, and `input_shape`. | [`paddleocr/_models/_text_detection.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/_text_detection.py) |
| **CLI Executor** | `TextDetectionSubcommandExecutor` registers the `text_detection` subcommand and forwards arguments to `perform_simple_inference`. | [`paddleocr/_models/text_detection.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/text_detection.py) |
| **Inference Engine** | `PaddleXPredictorWrapper` wraps `paddle.inference.create_predictor` to build the predictor from the supplied model directory. | [`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py) |
| **Post-Processing** | `PicoDetPostProcess` (or similar) thresholds the probability map, filters boxes by confidence, and applies the unclip operation. | [`ppocr/postprocess/picodet_postprocess.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/postprocess/picodet_postprocess.py) |

### Five-Step Detection Flow

1. **Load model** – Initialize the predictor using the specified weights and configuration.
2. **Pre-process image** – Scale the image according to `limit_side_len` and `limit_type` while preserving aspect ratio.
3. **Run inference** – Execute the neural network forward pass through the Paddle inference engine.
4. **Post-process** – Apply pixel-level thresholding (`thresh`), box-level filtering (`box_thresh`), non-maximum suppression, and box expansion via `unclip_ratio`.
5. **Return boxes** – Output a list of coordinates `[x_min, y_min, x_max, y_max]` with associated confidence scores.

## Running Text Detection via Command Line

The CLI provides the fastest way to use PaddleOCR for text detection on single images or batches without writing Python code.

```bash
paddleocr text_detection \
    -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png \
    --limit_side_len 960 \
    --thresh 0.3 \
    --box_thresh 0.5 \
    --unclip_ratio 2.0

```

The `text_detection` subcommand invokes `TextDetectionSubcommandExecutor`, which processes the image and outputs JSON containing bounding boxes and scores. Adjust `--limit_side_len` to control memory usage and inference speed for high-resolution images.

## Using the Python API for Stand-Alone Detection

For embedding detection into custom scripts, initialize `PaddleOCR` with recognition disabled to run only the detector.

```python
from paddleocr import PaddleOCR

# Initialize detector only (no recognizer)

ocr = PaddleOCR(
    det=True,                # explicitly enable detection (default)

    rec=False,               # disable recognition

    use_angle_cls=False,     # skip orientation classification

    limit_side_len=960,
    thresh=0.3,
    box_thresh=0.5,
    unclip_ratio=2.0,
)

# Run detection on a remote or local image

result = ocr.ocr(
    "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png",
    det=True,
    rec=False
)

# Parse results: list of dicts with 'box' and 'score' keys

for line in result:
    print(f"Box: {line['box']}, Score: {line['score']}")

```

The constructor forwards detection arguments to `TextDetectionMixin`, which validates and stores them for the inference stage. Setting `rec=False` skips the recognition model entirely, reducing latency when you only need bounding box coordinates.

## Integrating Detection into Full OCR Pipelines

To use PaddleOCR for text detection as part of a complete workflow that includes recognition, enable both stages in the constructor.

```python
from paddleocr import PaddleOCR

# Full pipeline: detection + recognition

ocr = PaddleOCR(
    use_angle_cls=False,
    limit_side_len=960,
    thresh=0.3,
    box_thresh=0.5,
    unclip_ratio=2.0,
)

# Process a local image

result = ocr.ocr("docs/images/demo_image/general_ocr_002.png")

# Each element contains the bounding box and recognized text tuple

for line in result:
    box, (text, score) = line
    print(f"Box: {box}, Text: '{text}', Score: {score:.3f}")

```

In this configuration, PaddleOCR first runs the detection model to generate candidate boxes, then feeds cropped regions to the recognition model. The output structure follows the `[bounding_box, (text, confidence)]` format documented in the repository README.

## Key Detection Parameters Explained

Tuning these parameters in [`paddleocr/_models/_text_detection.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/_text_detection.py) directly affects accuracy and inference speed.

| Parameter | Function | Typical Range |
|-----------|----------|---------------|
| **limit_side_len** | Maximum dimension (width or height) after resizing; larger values improve small-text detection but increase compute. | 640–960 |
| **limit_type** | Determines whether `limit_side_len` constrains the `max` (longer) or `min` (shorter) image side. | `max` or `min` |
| **thresh** | Pixel-level confidence threshold on the probability map; higher values reduce false positives. | 0.2–0.4 |
| **box_thresh** | Minimum average confidence inside a detected box; filters low-quality regions. | 0.5–0.7 |
| **unclip_ratio** | Multiplier expanding the shrunk polygon back to the full text region; increase for dense text. | 1.5–2.5 |
| **input_shape** | Static (C, H, W) tensor shape for optimized inference engines like TensorRT or ONNX. | (3, 640, 640) |

As implemented in [`ppocr/postprocess/picodet_postprocess.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/postprocess/picodet_postprocess.py), the post-processor first applies `thresh` to binarize the probability map, then averages pixel scores within each connected component to enforce `box_thresh`, and finally dilates the contour by `unclip_ratio` to recover the full text boundary.

## Summary

- **PaddleOCR text detection** is implemented through the `TextDetection` class, which combines `TextDetectionMixin` for configuration and `PaddleXPredictorWrapper` for inference.
- The pipeline executes five distinct stages: model loading, image preprocessing, neural network inference, post-processing (thresholding and unclipping), and result formatting.
- You can invoke detection via the `paddleocr text_detection` CLI for quick tasks or through the Python API by setting `rec=False` for stand-alone detection.
- Critical tuning parameters—`thresh`, `box_thresh`, `unclip_ratio`, and `limit_side_len`—control the trade-off between detection recall and precision.
- Source files [`paddleocr/_models/text_detection.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/text_detection.py) and [`ppocr/postprocess/picodet_postprocess.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/postprocess/picodet_postprocess.py) contain the core logic for model execution and result refinement.

## Frequently Asked Questions

### How do I adjust the sensitivity of text detection in PaddleOCR?

Modify the `thresh` and `box_thresh` parameters when initializing the `PaddleOCR` class. Lower `thresh` values (e.g., 0.2) detect faint or low-contrast text but may introduce noise, while higher `box_thresh` values (e.g., 0.6) filter out uncertain detections.

### What is the difference between `rec=False` and `det=True` in the Python API?

Setting `rec=False` disables the recognition model entirely, causing `ocr.ocr()` to return only bounding boxes and confidence scores. Setting `det=True` (the default) ensures the detection model runs; if both `det=True` and `rec=True`, the method returns recognized text alongside each box.

### Can I run PaddleOCR text detection without GPU support?

Yes, the `PaddleXPredictorWrapper` automatically falls back to CPU execution if PaddlePaddle is installed without CUDA support. Specify `--use_gpu false` in CLI commands or ensure no GPU flag is passed in Python to force CPU inference.

### Where is the bounding box expansion logic implemented?

The unclipping algorithm that expands detected boxes by the `unclip_ratio` multiplier resides in [`ppocr/postprocess/picodet_postprocess.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/postprocess/picodet_postprocess.py) within the `PicoDetPostProcess` class. This post-processor converts the shrunk text regions predicted by the neural network back to the original text boundaries.