### Install Nuitka

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/nuitka_package

Installs Nuitka. On first installation, mingw and ccache are automatically downloaded, or they can be configured manually.

```bash
pip install nuitka
```

--------------------------------

### Install OpenVINO

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Install the OpenVINO inference engine.

```bash
pip install openvino
```

--------------------------------

### Install pre-commit and enable Git hooks

Source: https://rapidai.github.io/RapidOCRDocs/latest/contributing?q=

Installs pre-commit and sets up the Git hook in the repository root. After installation, every git commit automatically runs configured formatters; if checks fail, the commit is rejected.

```bash
# 在 python 目录下、已激活的虚拟环境中安装
pip install pre-commit

# 到仓库根目录 RapidOCR 下安装 Git 钩子（.pre-commit-config.yaml 在根目录）
cd ..   # 若当前在 python 目录，先回到仓库根目录
pre-commit install
```

--------------------------------

### Run main.py to start the web service

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/ocrweb_multi?q=

Starts the OCR web service. After running, open http://127.0.0.1:8001 to use the application.

```bash
python main.py
```

--------------------------------

### Install rapidocr_web with pip

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/usage

Install the rapidocr_web package via pip.

```bash
pip install rapidocr_web
```

--------------------------------

### Start rapidocr_api on Windows with model paths

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage

Start the server on Windows by setting model paths via environment variables and then running rapidocr_api.

```bash
set det_model_path=I:\models\图像相关\OCR\RapidOCR\PP-OCRv4\ch_PP-OCRv4_det_server_infer.onnx
set rec_model_path=I:\models\图像相关\OCR\RapidOCR\PP-OCRv4\ch_PP-OCRv4_rec_server_infer.onnx
rapidocr_api
```

--------------------------------

### Install rapidocr_onnxruntime

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2023/10/17/%E5%A6%82%E4%BD%95%E6%9B%B4%E6%8D%A2%E5%85%B6%E4%BB%96%E6%A3%80%E6%B5%8B%E5%92%8C%E8%AF%86%E5%88%AB%E6%A8%A1%E5%9E%8B?q=

Install the rapidocr_onnxruntime package. This is the first step before using the library to load custom PaddleOCR models.

```bash
pip install rapidocr_onnxruntime

```

--------------------------------

### Start rapidocr_api on Linux with options

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage

Start the server on Linux with default parameters, specify IP, port, and worker count, and set model paths via environment variables.

```bash
# 默认参数启动
rapidocr_api

# 指定参数：端口与进程数量；
rapidocr_api -ip 0.0.0.0 -p 9005 -workers 2

# 指定模型
export det_model_path=/mnt/sda1/models/PP-OCRv4/ch_PP-OCRv4_det_server_infer.onnx
export rec_model_path=/mnt/sda1/models/PP-OCRv4/ch_PP-OCRv4_rec_server_infer.onnx
rapidocr_api -ip 0.0.0.0 -p 9005 -workers 2
```

--------------------------------

### Install rapidocr_api with pip

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage

Install the rapidocr_api package using pip.

```bash
pip install rapidocr_api
```

--------------------------------

### Install dependencies with pip

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/ocrweb_multi?q=

Changes into the ocrweb_multi directory and installs required Python packages using the Douban PyPI mirror. Run after cloning the repository.

```bash
cd ocrweb_multi
pip install -r requirements.txt -i https://pypi.douban.com/simple/
```

--------------------------------

### Install ONNX Runtime

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Install the ONNX Runtime inference engine. The CPU version is recommended; GPU is not recommended for use with rapidocr.

```bash
pip install onnxruntime
```

--------------------------------

### Example wheel filename

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/package/build-custom-version-rapidocr-whl?q=

Example of the generated wheel filename for version 3.1.0.

```text
dist/rapidocr-3.1.0-py3-none-any.whl
```

--------------------------------

### Install ONNX Runtime CANN

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Install the ONNX Runtime CANN execution provider. Supported only in rapidocr>=3.1.0.

```bash
pip install rapidocr onnxruntime-cann
```

--------------------------------

### RapidOCR API output example (with text)

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage

Example output when text is detected. Shows the structure with rec_txt, dt_boxes (coordinates), and score.

```json
{
 "0": {
  "rec_txt": "香港深圳抽血，", # 识别的文本
  "dt_boxes": [  # 依次为左上角 → 右上角 → 右下角 → 左下角
   [265, 18],
   [472, 231],
   [431, 271],
   [223, 59]
  ],
  "score": "0.8176"   # 置信度
 }
}
```

--------------------------------

### Install rapidocr with ONNX Runtime

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/install

Installs the rapidocr package along with the ONNX Runtime inference engine. This is the default installation command for rapidocr versions 2.0.6 and later, where ONNX Runtime is no longer a dependency and must be installed manually.

```bash
pip install rapidocr onnxruntime
```

--------------------------------

### Check RapidOCR installation with rapidocr check

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

Runs the RapidOCR installation check. It uses ONNX Runtime to process an image and verifies the result to determine if the library is installed correctly.

```bash
rapidocr check

```

--------------------------------

### Output of rapidocr download_models

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

Example output from running `rapidocr download_models`, showing the download initiation, size, and save location.

```text
[INFO] 2026-03-24 10:37:01,625 [RapidOCR] download_file.py:68: Initiating download: https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/v3.7.0/onnx/PP-OCRv4/cls/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2026-03-24 10:37:03,640 [RapidOCR] download_file.py:82: Download size: 0.56MB
[INFO] 2026-03-24 10:37:04,364 [RapidOCR] download_file.py:95: Successfully saved to: /Users/xxxx/RapidOCR/python/test_models/ch_ppocr_mobile_v2.0_cls_infer.onnx

```

--------------------------------

### Install dependencies and pytest

Source: https://rapidai.github.io/RapidOCRDocs/latest/contributing?q=

Installs project dependencies, pytest for running unit tests, and optionally installs the package in editable mode for local development.

```bash
pip install -r requirements.txt
pip install pytest  # 运行单元测试需要
# 可选：以可编辑模式安装当前包，便于调试
pip install -e .
```

--------------------------------

### Install datasets and text_det_metric

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/06/17/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv6-det-%E6%A8%A1%E5%9E%8B%E8%AE%B0%E5%BD%95?q=

Install the datasets and text_det_metric packages required for the model accuracy test using TextDetMetric and the text_det_test_dataset.

```bash
pip install datasets
pip install text_det_metric

```

--------------------------------

### Install rapidocr with Tsinghua mirror

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/install

Installs rapidocr using the Tsinghua mirror to speed up downloads when the default PyPI source is slow in China.

```bash
pip install rapidocr -i https://pypi.tuna.tsinghua.edu.cn/simple/
```

--------------------------------

### Dependencies for rapidocr

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/install

Lists the dependency packages required by rapidocr. If a dependency fails to install, install it individually first, then install rapidocr. Note the version constraints for Shapely and omegaconf.

```text
pyclipper>=1.2.0
opencv_python>=4.5.1.48
numpy>=1.19.5,<3.0.0
six>=1.15.0
Shapely>=1.7.1,!=2.0.4  # python3.12 2.0.4 bug
PyYAML
Pillow
tqdm
omegaconf!=2.2.1 # https://github.com/omry/omegaconf/issues/934
requests
colorlog
```

--------------------------------

### Install ONNX Runtime DirectML

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Install the ONNX Runtime DirectML execution provider. DirectML is only available on Windows 10 Build 18362 and above.

```bash
pip install rapidocr onnxruntime-directml
```

--------------------------------

### Test OCR with sample image

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/install

Runs a quick OCR test on a sample image. If the terminal prints the text content, the installation is successful.

```bash
rapidocr -img "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg" --vis_res
```

--------------------------------

### Install MNN with pip

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Install the MNN package using pip. Required for using MNN as the inference engine.

```bash
pip install MNN

```

--------------------------------

### EngineConfig YAML example

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/parameters

Example YAML configuration for the EngineConfig section, showing options for CUDA, PyTorch, TensorRT, and MNN inference engines. Includes settings for device, memory, and TensorRT profiles.

```yaml
use_cuda: false
cuda_ep_cfg:
    device_id: 0
    gpu_mem: 500

torch:
    use_cuda: false
    cuda_ep_cfg:
        device_id: 0

    use_npu: false
    npu_ep_cfg:
        device_id: 0

# rapidocr >= 3.7.0
tensorrt:
    device_id: 0
    use_fp16: true
    use_int8: false
    workspace_size: 1073741824  # 1GB = 1 << 30

    cache_dir: null
    force_rebuild: false

    det_profile:
        min_shape: [1, 3, 32, 32]
        opt_shape: [1, 3, 736, 736]
        max_shape: [1, 3, 2048, 2048]

    rec_profile:
        min_shape: [1, 3, 48, 32]
        opt_shape: [6, 3, 48, 320]
        max_shape: [6, 3, 48, 2048]

    cls_profile:
        min_shape: [1, 3, 48, 32]
        opt_shape: [6, 3, 48, 192]
        max_shape: [6, 3, 48, 192]

mnn: {}  # rapidocr>=3.6.0
```

--------------------------------

### Output of rapidocr config

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

Example output from running `rapidocr config`, indicating the location of the generated configuration file.

```text
The config file has saved in ./default_rapidocr.yaml

```

--------------------------------

### Verify installation with rapidocr check

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/install

Verifies installation for rapidocr versions 2.0.3 and later. The command `rapidocr check` outputs log lines and the final message 'Success! rapidocr is installed correctly!' to confirm success.

```bash
$ rapidocr check

# 输出以下内容即证明安装成功
[INFO] 2026-06-23 12:51:43,979 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,045 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_det_small.onnx
[INFO] 2026-06-23 12:51:44,046 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_det_small.onnx
[INFO] 2026-06-23 12:51:44,127 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,129 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/ch_ppocr_mobile_v2.0_cls_mobile.onnx
[INFO] 2026-06-23 12:51:44,129 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/ch_ppocr_mobile_v2.0_cls_mobile.onnx
[INFO] 2026-06-23 12:51:44,190 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,260 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_rec_small.onnx
[INFO] 2026-06-23 12:51:44,260 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_rec_small.onnx
Success! rapidocr is installed correctly!
```

--------------------------------

### Install MNN and convert PP-OCRv6 rec models to MNN

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/06/30/rapidocr-%E9%80%82%E9%85%8D-pp-ocrv6-rec-%E6%A8%A1%E5%9E%8B%E6%94%AF%E6%8C%81-paddle-pytorch-%E5%92%8C-mnn-%E8%AE%B0%E5%BD%95?q=

Install MNN version 3.2.5 and convert PP-OCRv6 rec ONNX models (medium, small, tiny) to MNN format using MNNConvert with the --bizCode MNN option.

```bash
# 安装
pip install MNN==3.2.5

# 转换
MNNConvert -f ONNX --modelFile modelscope/onnx/PP-OCRv6/rec/PP-OCRv6_rec_medium.onnx --MNNModel modelscope/mnn/PP-OCRv6/rec/PP-OCRv6_rec_medium.mnn --bizCode MNN

MNNConvert -f ONNX --modelFile modelscope/onnx/PP-OCRv6/rec/PP-OCRv6_rec_small.onnx --MNNModel modelscope/mnn/PP-OCRv6/rec/PP-OCRv6_rec_small.mnn --bizCode MNN

MNNConvert -f ONNX --modelFile modelscope/onnx/PP-OCRv6/rec/PP-OCRv6_rec_tiny.onnx --MNNModel modelscope/mnn/PP-OCRv6/rec/PP-OCRv6_rec_tiny.mnn --bizCode MNN

```

--------------------------------

### Install PaddleX OCR

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/06/17/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv6-det-%E6%A8%A1%E5%9E%8B%E8%AE%B0%E5%BD%95

Install PaddleX with OCR support, version 3.7.1, as required for using PP-OCRv6 detection models.

```bash
pip install "paddlex[ocr]==3.7.1"
```

--------------------------------

### Det YAML configuration example

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/parameters

Example YAML configuration for the Det section, specifying the detection engine, language, model type, and OCR version, along with detection-specific parameters like thresholds and image limits.

```yaml
Det:
    engine_type: "onnxruntime"
    lang_type: "ch"
    model_type: "small"
    ocr_version: "PP-OCRv6"

    task_type: "det"

    model_path: null
    model_dir: null

    limit_side_len: 736
    limit_type: min
    std: [ 0.5, 0.5, 0.5 ]
    mean: [ 0.5, 0.5, 0.5 ]

    thresh: 0.3
    box_thresh: 0.5
    max_candidates: 1000
    unclip_ratio: 1.6
    use_dilation: true
    score_mode: fast
```

--------------------------------

### OpenVINO log output

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Example log output showing that OpenVINO is being used. The line 'Using engine_name: openvino' confirms the engine.

```text
[INFO] 2025-03-21 09:28:03,457 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,553 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.onnx
[INFO] 2025-03-21 09:28:03,767 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,768 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2025-03-21 09:28:03,861 base.py:30: Using engine_name: openvino
[INFO] 2025-03-21 09:28:03,862 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.onnx
```

--------------------------------

### TextDetOutput example output

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

Example output of TextDetOutput showing fields: img (original image), boxes (text line coordinates as 4 points in order [top-left, top-right, bottom-right, bottom-left]), scores (confidence per box), and elapse (detection time in seconds).

```text
TextDetOutput(img=array([[[120,   3,  52],
    [130,   0,  63],
    [155,   9,  91],
    ...,
    [[122,   3,  54],
    [133,   1,  67],
    [157,  11,  93],
    ...,
    [187,  11, 135],
    [187,  11, 135],
    [186,  10, 134]]], dtype=uint8),
boxes=array([[[  6.,   2.],
    [322.,   9.],
    [320., 104.],
    [  4.,  97.]],
    ...,
    [[ 68., 391.],
    [151., 391.],
    [151., 413.],
    [ 68., 413.]],

    [[202., 391.],
    [287., 391.],
    [287., 413.],
    [202., 413.]]], dtype=float32),
scores=[0.8829081288294226, 0.8744070886972952, 0.8937022144061125],
elapse=0.15039170801173896)
```

--------------------------------

### Example RapidOCROutput result

Source: https://rapidai.github.io/RapidOCRDocs/latest/quickstart

Example output of the RapidOCROutput data class returned by the engine. Access boxes and txts directly via result.boxes and result.txts.

```python
RapidOCROutput(
    boxes=array([[[  6.,   2.],
        [322.,   9.],
        [320., 104.],
        [  4.,  97.]],

       [[ 70.,  98.],
        [252.,  98.],
        [252., 125.],
        [ 70., 125.]],

       [[ 68., 144.],
        [256., 144.],
        [256., 165.],
        [ 68., 165.]],

       [[108., 170.],
        [217., 170.],
        [217., 182.],
        [108., 182.]],

       [[ 35., 227.],
        [ 62., 227.],
        [ 62., 236.],
        [ 35., 236.]],

       [[139., 223.],
        [187., 223.],
        [187., 251.],
        [139., 251.]],

       [[ 35., 233.],
        [ 81., 236.],
        [ 80., 255.],
        [ 33., 252.]],

       [[257., 234.],
        [304., 236.],
        [303., 254.],
        [257., 253.]],

       [[259., 227.],
        [286., 226.],
        [287., 236.],
        [259., 237.]],

       [[140., 243.],
        [186., 245.],
        [186., 272.],
        [139., 271.]],

       [[129., 289.],
        [207., 290.],
        [206., 340.],
        [128., 338.]],

       [[ 98., 320.],
        [129., 320.],
        [129., 330.],
        [ 98., 330.]],

       [[205., 316.],
        [223., 316.],
        [223., 335.],
        [205., 335.]],

       [[114., 342.],
        [210., 342.],
        [210., 355.],
        [114., 355.]],

       [[ 68., 362.],
        [151., 362.],
        [151., 384.],
        [ 68., 384.]],

       [[202., 362.],
        [286., 362.],
        [286., 384.],
        [202., 384.]],

       [[ 68., 391.],
        [151., 391.],
        [151., 413.],
        [ 68., 413.]],

       [[202., 391.],
        [287., 391.],
        [287., 413.],
        [202., 413.]], dtype=float32),
    txts=('正品促销', '大桶装更划算', '强力去污符合国标', '40°C深度防冻不结冰', '日常价￥', '真击', '10.0起', '10.0起', '日常价￥', '底价', '5.8', '券后价￥', '起', '惊喜福利不容错过', '极速发货', '冰点标准', '破损就赔', '假一赔十'),
    scores=(0.99893, 0.9843, 0.97842, 0.93412, 0.81418, 0.66226, 0.99243, 0.99849, 0.81369, 0.99633, 0.9999, 0.83907, 0.99993, 0.99782, 0.99813, 0.99786, 0.92679, 0.99717),
    word_results=(None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None), elapse_list=[0.16008154186420143, 0.017705917358398438, 0.35501312371343374], elapse=0.5328005829360336)
```

--------------------------------

### Use DirectML with RapidOCR

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2024/07/13/how-to-use-directml?q=

Python usage example showing how to enable DirectML acceleration for detection, classification, and recognition by setting det_use_dml, cls_use_dml, and rec_use_dml to True. The default values are False.

```python
from rapidocr_onnxruntime import RapidOCR

engine = RapidOCR()

img_path = 'tests/test_files/ch_en_num.jpg'

# 默认都为False
result, elapse = engine(img_path, det_use_dml=True, cls_use_dml=True, rec_use_dml=True)
print(result)
print(elapse)
```

--------------------------------

### RapidOCR API example result

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage

Example output from the RapidOCR API showing multiple detected text regions with their bounding boxes and confidence scores.

```json
{
    "0": {
        "rec_txt": "8月26日！",
        "dt_boxes": [
            [333.0, 72.0],
            [545.0, 40.0],
            [552.0, 90.0],
            [341.0, 122.0]
        ],
        "score": "0.7342"
    },
    "1": {
        "rec_txt": "澳洲名校招生信息",
        "dt_boxes": [
            [266.0, 163.0],
            [612.0, 116.0],
            [619.0, 163.0],
            [272.0, 210.0]
        ],
        "score": "0.8262"
    },
    "2": {
        "rec_txt": "解读！！",
        "dt_boxes": [
            [341.0, 187.0],
            [595.0, 179.0],
            [598.0, 288.0],
            [344.0, 296.0]
        ],
        "score": "0.6152"
    },
    "3": {
        "rec_txt": "Rules...",
        "dt_boxes": [
            [446.0, 321.0],
            [560.0, 326.0],
            [559.0, 352.0],
            [445.0, 347.0]
        ],
        "score": "0.8704"
    }
}
```

--------------------------------

### Run rapidocr_web server on port 9003

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/usage

Start the OCR web service, binding to all interfaces on port 9003. After running, open http://localhost:9003/ in a browser (note: use http, not https).

```bash
rapidocr_web -ip 0.0.0.0 -p 9003
```

--------------------------------

### Example unit test for new feature

Source: https://rapidai.github.io/RapidOCRDocs/latest/contributing?q=

Example pytest test file for a new feature. Uses a fixture to create a RapidOCR engine and asserts that the result is not None. Test resources are expected in tests/test_files.

```python
# tests/test_xxx.py
import pytest
from pathlib import Path

root_dir = Path(__file__).resolve().parent.parent
tests_dir = root_dir / "tests" / "test_files"

@pytest.fixture()
def engine():
    from rapidocr import RapidOCR
    return RapidOCR()

def test_your_new_feature(engine):
    img_path = tests_dir / "ch_en_num.jpg"
    result = engine(img_path)
    assert result is not None
    # 更多断言...
```

--------------------------------

### 安装构建工具和依赖

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/package/build-custom-version-rapidocr-whl

升级 pip 并安装构建所需的 setuptools、wheel、setuptools-scm 和 PyYAML。

```bash
python -m pip install --upgrade pip
python -m pip install build setuptools wheel setuptools-scm PyYAML
```

--------------------------------

### ONNX Runtime log output

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/how_to_use_infer_engine

Example log output showing that ONNX Runtime is being used. The line 'Using engine_name: onnxruntime' confirms the engine.

```text
[INFO] 2025-03-21 09:28:03,457 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,553 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_det_infer.onnx
[INFO] 2025-03-21 09:28:03,767 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,768 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2025-03-21 09:28:03,861 base.py:30: Using engine_name: onnxruntime
[INFO] 2025-03-21 09:28:03,862 utils.py:35: File already exists in /Users/joshuawang/projects/_self/RapidOCR/python/rapidocr/models/ch_PP-OCRv4_rec_infer.onnx
```

--------------------------------

### Call RapidOCR engine with return_word_box and return_single_char_box

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/parameters

Example call to the RapidOCR engine with return_word_box and return_single_char_box enabled. return_single_char_box only takes effect when return_word_box is True.

```python
result = engine(img_url, return_word_box=True, return_single_char_box=True)

```

--------------------------------

### 准备默认模型资源

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/package/build-custom-version-rapidocr-whl

运行 prepare_wheel_assets.py 下载或校验默认模型，并生成 MANIFEST.in 以确保模型被打入 wheel。

```bash
python tools/prepare_wheel_assets.py
```

--------------------------------

### Dependency versions for RapidOCR vs PaddleOCR benchmark

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/02/06/rapidocr-vs-paddleocr

Lists the exact dependency versions used in the benchmark environment (macOS Tahoe 26.2, Apple M2, Python 3.10.0). Install these versions to reproduce the comparison.

```text
rapidocr==3.6.0
onnxruntime==1.22.0
paddleocr==3.4.0
paddlepaddle==3.1.0
paddlex==3.4.1
numpy==2.2.6
opencv-python==4.11.0.86
```

--------------------------------

### Output of rapidocr check

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

Example output from running `rapidocr check`. It shows the ONNX Runtime engine being used, model files being located, and ends with the success message.

```text
[INFO] 2026-06-23 12:51:43,979 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,045 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_det_small.onnx
[INFO] 2026-06-23 12:51:44,046 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_det_small.onnx
[INFO] 2026-06-23 12:51:44,127 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,129 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/ch_ppocr_mobile_v2.0_cls_mobile.onnx
[INFO] 2026-06-23 12:51:44,129 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/ch_ppocr_mobile_v2.0_cls_mobile.onnx
[INFO] 2026-06-23 12:51:44,190 [RapidOCR] base.py:23: Using engine_name: onnxruntime
[INFO] 2026-06-23 12:51:44,260 [RapidOCR] download_file.py:60: File exists and is valid: /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_rec_small.onnx
[INFO] 2026-06-23 12:51:44,260 [RapidOCR] main.py:63: Using /usr/local/lib/python3.12/dist-packages/rapidocr/models/PP-OCRv6_rec_small.onnx
Success! rapidocr is installed correctly!

```

--------------------------------

### 运行 main.py

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_web/ocrweb_multi

在项目根目录下运行 main.py 启动服务，默认监听 8001 端口。

```bash
python main.py

```

--------------------------------

### Convert PP-OCRv6_tiny_det to ONNX with PaddleX

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/06/17/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv6-det-%E6%A8%A1%E5%9E%8B%E8%AE%B0%E5%BD%95?q=

Install paddle2onnx and onnx==1.17.0, then convert the PP-OCRv6_tiny_det Paddle model to ONNX format using PaddleX's paddle2onnx command. The output is saved to models/PP-OCRv6_det_tiny.

```bash
paddlex --install paddle2onnx
pip install onnx==1.17.0

paddlex --paddle2onnx --paddle_model_dir models/official_models/PP-OCRv6_tiny_det --onnx_model_dir models/PP-OCRv6_det_tiny

```

--------------------------------

### Run RapidOCR with specified model parameters

Source: https://rapidai.github.io/RapidOCRDocs/latest/model_list

Use this snippet to run OCR with RapidOCR by specifying model parameters directly. The engine automatically downloads the required model files. This example uses PP-OCRv5 with the Paddle engine and mobile model type, processes an image from a URL, prints the result, and saves a visualization to 'vis_result.jpg'.

```python
from rapidocr import EngineType, LangDet, ModelType, OCRVersion, RapidOCR

engine = RapidOCR(
    params={
        "Rec.ocr_version": OCRVersion.PPOCRV5,
        "Rec.engine_type": EngineType.PADDLE,
        "Rec.model_type": ModelType.MOBILE,
    }
)

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis("vis_result.jpg")
```

--------------------------------

### 指定版本号并构建 wheel

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/package/build-custom-version-rapidocr-whl

通过 SETUPTOOLS_SCM_PRETEND_VERSION_FOR_RAPIDOCR 环境变量指定版本号，然后构建 wheel。

```bash
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_RAPIDOCR=3.1.0 python -m build --wheel
```

--------------------------------

### Configure CoreMLProvider in RapidOCR

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/02/28/coreml-vs-cpu-provider-onnxruntime-rapidocr

Shows how to enable CoreMLProvider via the EngineConfig.onnxruntime.use_coreml parameter, and how to use the default CPUProvider by omitting the parameter. The CPUProvider is recommended on macOS based on the benchmark results.

```python
from rapidocr import RapidOCR

# 使用 CoreMLProvider
engine = RapidOCR(params={
    "EngineConfig.onnxruntime.use_coreml": True,
})

# 使用默认 CPUProvider（推荐）
engine = RapidOCR()
```

--------------------------------

### RapidOCR + ONNX Runtime 推理 Rec 模型（Exp1 Step 1）

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/01/21/rapidocr-support-mnn-engine?q=

使用 RapidOCR 和 ONNX Runtime 格式模型进行推理，加载 ch_PP-OCRv4_rec_mobile.onnx 模型，对测试数据集逐张图片执行识别，并将结果写入 pred.txt。

```python
import time

import cv2
import numpy as np
from datasets import load_dataset
from tqdm import tqdm

from rapidocr import EngineType, OCRVersion, RapidOCR

model_path = "rapidocr/models/ch_PP-OCRv4_rec_mobile.onnx"
dict_path = "rapidocr/models/ppocr_keys_v1.txt"
engine = RapidOCR(
    params={
        "Rec.model_path": model_path,
        "Rec.rec_keys_path": dict_path,
    }
)

dataset = load_dataset("SWHL/text_rec_test_dataset")
test_data = dataset["test"]

content = []
for i, one_data in enumerate(tqdm(test_data)):
    img = np.array(one_data.get("image"))
    img = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)

    t0 = time.perf_counter()
    result = engine(img, use_rec=True, use_cls=False, use_det=False)
    elapse = time.perf_counter() - t0

    rec_text = result.txts[0]
    if len(rec_text) <= 0:
        rec_text = ""
        elapse = 0

    gt = one_data.get("label", None)
    content.append(f"{rec_text}\t{gt}\t{elapse}")

with open("pred.txt", "w", encoding="utf-8") as f:
    for v in content:
        f.write(f"{v}\n")
```

--------------------------------

### 测试 enable_cpu_mem_arena 的 Python 代码

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2022/09/23/onnx-runtime-cpu-%E6%8E%A8%E7%90%86%E4%BC%98%E5%8C%96?q=

使用 memory_profiler 和 onnxruntime 测试 enable_cpu_mem_arena 参数对内存占用的影响。需要安装 onnxruntime==1.14.1 和 memory_profiler，并准备 enable_cpu_memory_area_example 目录下的 input.npy 和 model.onnx 文件。

```python
# pip install onnxruntime==1.14.1
# pip install memory_profiler

import numpy as np
import onnxruntime as ort
from memory_profiler import profile


@profile
def onnx_prediction(model_path, input_data):
    ort_sess = ort.InferenceSession(model_path, sess_options=sess_options)
    preds = ort_sess.run(output_names=["predictions"],
                            input_feed={"input_1": input_data})[0]
    return preds


sess_options = ort.SessionOptions()
sess_options.enable_cpu_mem_arena = False

input_data = np.load('enable_cpu_memory_area_example/input.npy')
print(f'input_data shape: {input_data.shape}')
model_path = 'enable_cpu_memory_area_example/model.onnx'

onnx_prediction(model_path, input_data)
```

--------------------------------

### Run rapidocr_api on Windows with model env vars

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr_api/usage?q=

For Windows, set environment variables for the detection and recognition models, then run the server.

```bash
set det_model_path=I:\models\图像相关\OCR\RapidOCR\PP-OCRv4\ch_PP-OCRv4_det_server_infer.onnx
set rec_model_path=I:\models\图像相关\OCR\RapidOCR\PP-OCRv4\ch_PP-OCRv4_rec_server_infer.onnx
rapidocr_api

```

--------------------------------

### 转换 PP-OCRv5_server_det 模型

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2025/05/26/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv5_det-%E6%A8%A1%E5%9E%8Bmobileserver%E8%AE%B0%E5%BD%95

执行 PaddleX 的 ONNX 转换命令以处理 server 版本模型。

```bash
paddlex --install paddle2onnx
pip install onnx==1.16.0

paddlex --paddle2onnx --paddle_model_dir models/official_models/PP-OCRv5_server_det --onnx_model_dir models/PP-OCRv5_server_det
```

--------------------------------

### 生成默认配置文件

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage

在终端执行 rapidocr config 命令，在当前目录下生成默认的 default_rapidocr.yaml 配置文件。

```bash
$ rapidocr config
# The config file has saved in ./default_rapidocr.yaml

```

--------------------------------

### 测试 PP-OCRv4_server_rec_doc 模型识别

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2025/05/16/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv4_server_rec_doc-%E6%A8%A1%E5%9E%8B%E8%AE%B0%E5%BD%95

使用 PaddleX 创建模型并预测图片，输出识别结果。模型会自动下载到 /Users/用户名/.paddlex/official_models 目录。

```python
from paddlex import create_model

model = create_model(model_name="PP-OCRv4_server_rec_doc")
output = model.predict(input="images/1.jpg", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

# 输出以下内容，表明成功：
# {'res': {'input_path': 'images/1.jpg', 'page_index': None, 'rec_text': '绿洲仕格维花园公寓', 'rec_score': 0.9839767813682556}}
```

--------------------------------

### 使用 paddlex 命令转换 PP-OCRv6_tiny_rec 模型为 ONNX

Source: https://rapidai.github.io/RapidOCRDocs/latest/blog/2026/06/18/rapidocr-%E9%9B%86%E6%88%90-pp-ocrv6-rec-%E6%A8%A1%E5%9E%8B%E8%AE%B0%E5%BD%95

使用 PaddleX 的 --paddle2onnx 参数将 Paddle 格式的 PP-OCRv6_tiny_rec 模型转换为 ONNX 格式，输出目录为 models/PP-OCRv6_rec_tiny。

```bash
paddlex --paddle2onnx --paddle_model_dir models/official_models/PP-OCRv6_tiny_rec --onnx_model_dir models/PP-OCRv6_rec_tiny
```

--------------------------------

### RapidOCR result example

Source: https://rapidai.github.io/RapidOCRDocs/latest/quickstart?q=

Example output of the RapidOCR engine. The result is a RapidOCROutput data class with boxes, txts, scores, word_results, elapse_list, and elapse attributes.

```python
RapidOCROutput(
    boxes=array([[[  6.,   2.],
        [322.,   9.],
        [320., 104.],
        [  4.,  97.]],

       [[ 70.,  98.],
        [252.,  98.],
        [252., 125.],
        [ 70., 125.]],

       [[ 68., 144.],
        [256., 144.],
        [256., 165.],
        [ 68., 165.]],

       [[108., 170.],
        [217., 170.],
        [217., 182.],
        [108., 182.]],

       [[ 35., 227.],
        [ 62., 227.],
        [ 62., 236.],
        [ 35., 236.]],

       [[139., 223.],
        [187., 223.],
        [187., 251.],
        [139., 251.]],

       [[ 35., 233.],
        [ 81., 236.],
        [ 80., 255.],
        [ 33., 252.]],

       [[257., 234.],
        [304., 236.],
        [303., 254.],
        [257., 253.]],

       [[259., 227.],
        [286., 226.],
        [287., 236.],
        [259., 237.]],

       [[140., 243.],
        [186., 245.],
        [186., 272.],
        [139., 271.]],

       [[129., 289.],
        [207., 290.],
        [206., 340.],
        [128., 338.]],

       [[ 98., 320.],
        [129., 320.],
        [129., 330.],
        [ 98., 330.]],

       [[205., 316.],
        [223., 316.],
        [223., 335.],
        [205., 335.]],

       [[114., 342.],
        [210., 342.],
        [210., 355.],
        [114., 355.]],

       [[ 68., 362.],
        [151., 362.],
        [151., 384.],
        [ 68., 384.]],

       [[202., 362.],
        [286., 362.],
        [286., 384.],
        [202., 384.]],

       [[ 68., 391.],
        [151., 391.],
        [151., 413.],
        [ 68., 413.]],

       [[202., 391.],
        [287., 391.],
        [287., 413.],
        [202., 413.]],
    dtype=float32),
    txts=('正品促销', '大桶装更划算', '强力去污符合国标', '40°C深度防冻不结冰', '日常价￥', '真击', '10.0起', '10.0起', '日常价￥', '底价', '5.8', '券后价￥', '起', '惊喜福利不容错过', '极速发货', '冰点标准', '破损就赔', '假一赔十'),
    scores=(0.99893, 0.9843, 0.97842, 0.93412, 0.81418, 0.66226, 0.99243, 0.99849, 0.81369, 0.99633, 0.9999, 0.83907, 0.99993, 0.99782, 0.99813, 0.99786, 0.92679, 0.99717),
    word_results=(None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None), elapse_list=[0.16008154186420143, 0.017705917358398438, 0.35501312371343374], elapse=0.5328005829360336)
```

--------------------------------

### Basic RapidOCR Usage with Defaults

Source: https://rapidai.github.io/RapidOCRDocs/latest/install_usage/rapidocr/usage?q=

Initialize RapidOCR with default parameters and perform OCR on an image URL, then print the result and save a visualization.

```python
from rapidocr import RapidOCR

engine = RapidOCR()

img_url = "https://www.modelscope.cn/models/RapidAI/RapidOCR/resolve/master/resources/test_files/ch_en_num.jpg"
result = engine(img_url)
print(result)

result.vis("vis_result.jpg")
```