Install & Compatibility
Where this runs
tested against v3.3.1 · 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
py 3.10
✕ build_error
✓ 22.35s
py 3.11
✕ build_error
✓ 20.2s
py 3.12
✕ build_error
✓ 20s
py 3.13
✕ build_error
1/2 runs
py 3.9
✕ build_error
✓ 23.5s
852MB installed
● package 852MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart code verifies the PaddlePaddle installation by running a built-in check. It then demonstrates basic tensor creation and a matrix multiplication operation, also indicating whether a GPU is detected and utilized.
import paddle
# Verify PaddlePaddle installation
print(f"PaddlePaddle installation check: {'Success!' if paddle.utils.run_check() else 'Failed.'}")
# Create a tensor
x = paddle.to_tensor([[1.0, 2.0], [3.0, 4.0]])
print(f"\nOriginal tensor:\n{x}")
# Perform a simple operation (e.g., matrix multiplication)
y = paddle.to_tensor([[5.0, 6.0], [7.0, 8.0]])
z = paddle.matmul(x, y)
print(f"Result of matrix multiplication:\n{z}")
# Check if GPU is available and currently used
if paddle.is_compiled_with_cuda():
print(f"\nCUDA is available. Current device: {paddle.get_device()}")
else:
print("\nCUDA is not available. Running on CPU.")
paddle --version
Debug
Known issues
breakingPaddlePaddle 2.0 introduced significant changes, making dynamic graph mode the default and adjusting the API directory system. While older APIs might be compatible, new development should adopt the updated API system for best practices and future compatibility.fixReview the PaddlePaddle 2.0 Upgrade Guide and transition to the new API system, favoring dynamic graph mode. Explicitly enable static graph mode if needed via `paddle.enable_static()`.
affects: 2.0 and later
gotchaSub-libraries or related projects within the PaddlePaddle ecosystem (e.g., PaddleOCR) have sometimes introduced breaking changes in minor or micro version updates, deviating from strict semantic versioning. This can lead to unexpected behavior if not pinning exact versions.fixAlways pin exact versions of `paddlepaddle` and any related sub-libraries (e.g., `paddleocr==X.Y.Z`) in your `requirements.txt` to prevent unforeseen issues from automatic updates. Regularly check release notes for breaking changes before upgrading.
affects: Various sub-library versions (e.g., PaddleOCR 2.6.0 to 2.6.1)
gotchaInstalling the GPU version (`paddlepaddle-gpu`) requires strict compatibility with your CUDA Toolkit, cuDNN, and NVIDIA GPU driver versions. Mismatches are a frequent source of installation failures or runtime errors.fixRefer to the official PaddlePaddle installation guide for the exact CUDA, cuDNN, and driver versions compatible with your desired `paddlepaddle-gpu` version. Ensure your system meets all prerequisites before installation.
affects: All GPU versions
gotchaPaddlePaddle has specific Python and pip version requirements. For example, Python 3.8-3.12 (or 3.9-3.13 on Linux) and pip 20.2.2+ are generally required, and the installation environment must be 64-bit.fixVerify your Python interpreter and pip are 64-bit and meet the version requirements specified in the official installation documentation for your operating system. Use `python3 -c "import platform; print(platform.architecture()[0]); print(platform.machine())"` to check architecture and `python3 --version` and `python3 -m pip --version` for versions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'paddle'
This error occurs when the PaddlePaddle library is not installed in the current Python environment.
fixInstall PaddlePaddle using pip: `pip install paddlepaddle`.
ImportError: cannot import name 'inference' from 'paddle'
This error occurs when attempting to import a module or function that has been deprecated or removed in the installed version of PaddlePaddle.
fixEnsure you are using compatible versions of PaddlePaddle and related libraries, and update your code to use the current API.
ModuleNotFoundError: No module named 'paddle.fluid.core_noavx'
This error occurs when the installed PaddlePaddle version is incompatible with the CPU architecture, particularly if the CPU lacks AVX support.
fixInstall the no-AVX version of PaddlePaddle: `pip install paddlepaddle -f https://paddlepaddle.org.cn/whl/stable/noavx.html`.
ImportError: cannot import name 'PaddleOCR' from partially initialized module 'paddleocr' (most likely due to a circular import)
This error occurs when the script's filename is the same as the module being imported, leading to a circular import.
fixRename your script to avoid naming conflicts with the 'paddleocr' module.
ImportError: cannot import name 'soft_relu' from 'paddle.nn.functional'
This error occurs when attempting to import a function that has been removed or renamed in the current version of PaddlePaddle.
fixCheck the PaddlePaddle documentation for the updated function name or alternative, and update your code accordingly.
Upgrade
Version history
3.3.1latest on PyPI · released Mar 26, 2026
Audit
Dependencies
numpyrequiredCore numerical operations dependency.
CUDA ToolkitoptionalRequired for GPU version (e.g., CUDA 11.8 or 12.6 for recent PaddlePaddle versions on Linux; 10.2/11.2/11.6/11.7 on Windows).
cuDNNoptionalRequired for GPU version (e.g., cuDNN 7.6.5+).
NVIDIA GPU DriveroptionalLatest compatible driver for your GPU and CUDA version.