Install & Compatibility
Where this runs
tested against v3.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
no_wheel
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 56.9s · import 0.000s · 3788.8MB
3260MB installed
● package 3260MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PaddleOCR
✓ from paddleocr import 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.
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)
paddleocr --version
Debug
Known issues
breakingPaddleOCR 3.x introduced significant interface changes compared to 2.x versions. Code written for 2.x will likely break with 3.x.fixRefer to the official documentation for PaddleOCR 3.x to update code. Pin PaddleOCR and PaddlePaddle versions in your project's dependencies.
affects: 3.0.0 and above
gotchaIncompatible `PaddlePaddle` framework versions can lead to runtime errors, especially with GPU usage (CUDA/cuDNN issues). `paddleocr` requires PaddlePaddle 3.0 or above.fixAlways 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.
affects: All versions
gotchaWhen processing PDF files, `AttributeError` related to `pymupdf` (e.g., 'Document' object has no attribute 'metadata') can occur due to version conflicts.fixIf `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`.
affects: All versions (specific to pymupdf dependency)
gotchaGPU installations can frequently encounter `RuntimeError: (PreconditionNotMet) Cannot load cudnn shared library` or similar. This often means PaddleOCR cannot find required CUDA/cuDNN libraries.fixEnsure `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.
affects: All GPU-enabled versions
gotchaDefault models may not achieve optimal accuracy for specific text types (e.g., numeric-only) or challenging image conditions (low contrast, noise).fixExperiment 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.
affects: All versions
Upgrade
Version history
3.7.0latest on PyPI · released Jun 11, 2026
Audit
Dependencies
paddlepaddlerequiredEssential deep learning framework runtime for all PaddleOCR functionalities.
pymupdfoptionalUsed for PDF document processing, but specific version conflicts can occur.
layoutparseroptionalRequired for advanced layout analysis features.