PaddleOCR

3.4.0 · active · verified Sat Apr 11

PaddleOCR is an awesome multilingual OCR and document parsing toolkit built upon the PaddlePaddle deep learning framework. It provides robust capabilities for text detection, text recognition, and structured document understanding, capable of transforming images and PDFs into structured data (JSON/Markdown) for AI and LLM-based applications. The library is currently at version 3.4.0 and maintains a frequent release cadence, with minor versions released every few months, incorporating new models and features.

Warnings

breaking PaddleOCR 3.x introduced significant interface changes compared to 2.x versions. Code written for 2.x will likely break with 3.x.
Fix: Refer to the official documentation for PaddleOCR 3.x to update code. Pin PaddleOCR and PaddlePaddle versions in your project's dependencies.
gotcha Incompatible `PaddlePaddle` framework versions can lead to runtime errors, especially with GPU usage (CUDA/cuDNN issues). `paddleocr` requires PaddlePaddle 3.0 or above.
Fix: Always install the `paddlepaddle` framework first, ensuring its version is compatible with your `paddleocr` installation and GPU environment (e.g., CUDA version). Consult PaddlePaddle's official installation guide for specific platform/CUDA versions.
gotcha When processing PDF files, `AttributeError` related to `pymupdf` (e.g., 'Document' object has no attribute 'metadata') can occur due to version conflicts.
Fix: If `paddleocr[all]` causes issues with PDFs, try uninstalling `pymupdf` and installing a specific compatible version, for example: `pip uninstall pymupdf` then `pip install pymupdf==1.19.0`.
gotcha GPU installations can frequently encounter `RuntimeError: (PreconditionNotMet) Cannot load cudnn shared library` or similar. This often means PaddleOCR cannot find required CUDA/cuDNN libraries.
Fix: Ensure `libcublas.so` and `libcudnn.so` (and potentially other cuDNN files) are correctly linked or discoverable in `/usr/lib` or other system library paths. Creating symbolic links to the actual library locations is a common solution.
gotcha Default models may not achieve optimal accuracy for specific text types (e.g., numeric-only) or challenging image conditions (low contrast, noise).
Fix: Experiment with different PaddleOCR model versions (e.g., PP-OCRv5 for general scenes), preprocess images to improve quality, or fine-tune models on domain-specific datasets. Adjust parameters like `rec_image_shape` or enable `use_angle_cls` as needed.

Install

pip install paddlepaddle pip install paddleocr Basic OCR (CPU)
pip install paddlepaddle-gpu # Or specific CUDA version, see PaddlePaddle docs pip install "paddleocr[all]" Full features (GPU)

Imports

PaddleOCR
```
from paddleocr import PaddleOCR
```
The primary class for OCR inference is PaddleOCR.
PaddleOCRVL
```
from paddleocr import PaddleOCRVL
```
Used for advanced Vision-Language model (VLM) document parsing tasks, available with [doc-parser] extra.

Quickstart

This quickstart demonstrates how to perform basic OCR on an image using the `PaddleOCR` class. It initializes the OCR engine (downloading models if not present), processes a dummy image, and prints the detected text along with its confidence score. For document parsing with VLM, use `PaddleOCRVL`.

from paddleocr import PaddleOCR
import os
import cv2
import numpy as np

# Create a dummy image for demonstration
img_path = 'temp_ocr_test_image.png'
img = np.zeros((100, 300, 3), dtype=np.uint8)
cv2.putText(img, 'Hello PaddleOCR!', (10, 60), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
cv2.imwrite(img_path, img)

# Initialize PaddleOCR with default language (Chinese & English) or specify 'en' for English
# Models will be downloaded automatically on first use
ocr = PaddleOCR(use_angle_cls=True, lang='en', show_log=False)

# Perform OCR on the image
result = ocr.ocr(img_path, cls=True)

# Print detected text and confidence scores
for idx in range(len(result)):
    res = result[idx]
    for line in res:
        print(f"Text: {line[1][0]}, Confidence: {line[1][1]:.2f}")

# Clean up dummy image
os.remove(img_path)

view raw JSON →