Install & Compatibility
Where this runs
tested against v3.7.2 · 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
788MB installed
● package 788MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_pipeline
✓ from paddlex import create_pipeline
This quickstart demonstrates how to initialize an OCR pipeline and perform inference on an image URL using the `create_pipeline` function and its `predict` method. The example uses a public image URL, but local file paths are also supported.
import os
from paddlex import create_pipeline
# Example for OCR pipeline
# Note: This quickstart assumes PaddlePaddle and necessary OCR dependencies are installed.
# You can replace 'OCR' with other supported pipeline names (e.g., 'GeneralInstanceSegmentation', 'ImageMultiLabelClassification').
# The 'input' can be a local path, directory, or URL to an image.
# For a real-world scenario, you might download an image or use a local file.
image_url = "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png"
try:
# Create an OCR pipeline instance
pipeline = create_pipeline(pipeline="OCR")
print("OCR pipeline created successfully.")
# Predict using the pipeline
# The 'predict' method returns a dictionary of results.
output = pipeline.predict(image_url)
# Print the prediction results
print("Prediction successful. Output:")
print(output)
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure PaddlePaddle is installed and compatible, and relevant PaddleX dependencies (e.g., 'paddlex[ocr]') are installed.")
paddlex --version
Debug
Known issues
breakingPaddleX 3.0.x requires PaddlePaddle version 3.0.0 or higher. Older PaddlePaddle versions are incompatible and will lead to runtime errors.fixEnsure `paddlepaddle` or `paddlepaddle-gpu` is installed with version `3.0.0` or higher before installing PaddleX.
affects: <3.0.0
gotchaOn Python 3.12 and newer, `setuptools` is no longer included by default in virtual environments. This can cause installation failures for PaddlePaddle and subsequently PaddleX.fixExplicitly install `setuptools` (e.g., `pip install setuptools`) in your virtual environment before installing PaddlePaddle or PaddleX.
affects: Python >=3.12
gotchaWhen using the high-performance inference plugin, ensure the installed TensorRT version is compatible with your PaddlePaddle's CUDA version. For example, PaddlePaddle with CUDA 11.8 requires TensorRT 8.x (specifically recommended 8.6.1.6).fixRefer to the PaddleX documentation for compatible TensorRT versions corresponding to your PaddlePaddle/CUDA setup and install it manually if necessary.
affects: All versions using high-performance inference on GPU
deprecatedIn PaddleX 3.0, static graph models for inference now use `.json` files instead of the older `.pdmodel` format. Using the old format with newer PaddleX versions for static graph inference may not work as expected.fixEnsure your models are updated to the `.json` format for static graph inference with PaddleX 3.0+. Convert older `.pdmodel` files if you encounter issues.
affects: PaddleX <3.0.0 (using .pdmodel)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'paddlex'
The 'paddlex' library is not installed in the current Python environment or the environment is not activated.
fixEnsure you have activated the correct Python environment and install PaddleX using: `pip install paddlex`
ImportError: cannot import name 'transforms' from 'paddlex'
This error commonly occurs due to a circular import, often when a local Python file or directory is named 'paddlex.py', which conflicts with the installed PaddleX package. It can also indicate an API change where 'transforms' is no longer directly available from the top-level 'paddlex' package.
fixRename any local file or directory named 'paddlex.py' or similar that might be causing a naming conflict. If it's an API change, try importing from the specific submodule, e.g., `from paddlex.transforms import Compose` or `import paddlex.transforms as T`.
AttributeError: module 'paddle' has no attribute 'device'
This issue typically arises from an incompatibility between the installed 'paddlex' version and the 'paddlepaddle' version, where the 'paddle.device' API has changed or is not present in the installed PaddlePaddle.
fixInstall a PaddlePaddle version that is compatible with your PaddleX installation. Refer to the official PaddleX documentation for recommended PaddlePaddle versions, or try updating both libraries to their latest compatible versions.
AttributeError: module 'cv2' has no attribute 'IMREAD_COLOR'
This error points to a conflict or an incorrect installation of OpenCV (cv2) in your environment, often caused by having multiple OpenCV variants installed simultaneously.
fixUninstall all conflicting OpenCV packages (e.g., `pip uninstall opencv-python opencv-contrib-python opencv-python-headless`) and then reinstall a single, compatible version, usually `pip install opencv-python`.
paddlex.utils.errors.others.UnsupportedParamError: 'SLANet_plus' is not a registered model name.
The specified model name is not recognized or registered within the PaddleX framework, likely because the required plugin for that model has not been installed, or the model name is misspelled.
fixVerify the exact model name in the official PaddleX documentation and ensure you have installed the necessary plugin for the model, for example, by running `paddlex --install PaddleClas` or `pip install "paddlex[ocr]"` for specific features.
Upgrade
Version history
3.7.2latest on PyPI · released Jun 25, 2026
Audit
Dependencies
paddlepaddlerequiredCore deep learning framework. PaddleX 3.0.x versions depend on PaddlePaddle 3.0.0 and above for compatibility.
setuptoolsoptionalRequired for Python 3.12+ environments, as it's no longer included by default in virtual environments, preventing PaddleX and PaddlePaddle installation issues.
TensorRToptionalRequired for high-performance inference with specific GPU configurations (e.g., CUDA 11.8 compatible TensorRT 8.x).