Install & Compatibility
Where this runs
tested against v5.0.0.93 · 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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.000s · 292MB
293MB installed
● package 293MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart creates a simple black image with 'Hello, OpenCV!' text, displays it in a window, waits for a key press, and then closes the window. This demonstrates basic image creation, text overlay, and GUI handling.
import cv2
import numpy as np
# Create a dummy image (black background with white text)
img = np.zeros((300, 500, 3), dtype=np.uint8)
cv2.putText(img, "Hello, OpenCV!", (50, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
# Display the image
cv2.imshow("Dummy Image", img)
# Wait indefinitely until a key is pressed
cv2.waitKey(0)
# Destroy all OpenCV windows
cv2.destroyAllWindows()
Debug
Known issues
gotchaThere are two main OpenCV Python packages: `opencv-python` and `opencv-contrib-python`. `opencv-python` contains the core modules, while `opencv-contrib-python` includes additional modules (e.g., SIFT, SURF, XFEATURES2D) that might have licensing restrictions or are less stable. Do NOT install both; choose the one that suits your needs. Installing `opencv-contrib-python` is sufficient if you require the 'extra' modules.fixEnsure you only `pip install opencv-contrib-python` if you need the contrib modules, or `pip install opencv-python` otherwise. Uninstalling one before installing the other can prevent conflicts.
affects: All versions
gotchaOpenCV's GUI functions (`cv2.imshow`, `cv2.waitKey`, `cv2.destroyAllWindows`) require a display server to function correctly. Running these on headless servers (e.g., via SSH without X forwarding, or Docker containers without a display setup) will fail or raise exceptions (e.g., 'no display specified').fixFor headless environments, avoid GUI functions or consider specific headless builds (e.g., `opencv-python-headless`). Ensure your environment has a configured display server if GUI operations are necessary. For development, use X forwarding or VNC if connecting remotely.
affects: All versions
breakingOpenCV Python bindings are built against specific versions of NumPy. Installing an incompatible NumPy version can lead to runtime errors (e.g., 'ImportError: numpy.core.multiarray failed to import') or unexpected behavior. Recent versions (4.10.0.84+) support NumPy 2.x for Python 3.9+, while older Python versions might require NumPy 1.x.fixAlways install NumPy first, then OpenCV. Check the official OpenCV release notes or wheel tags for specific NumPy compatibility information. If you encounter errors, try downgrading or upgrading your NumPy package to align with what your `opencv-contrib-python` wheel expects.
affects: All versions, especially around NumPy 2.x transition (OpenCV 4.10.0.84 onwards for Python 3.9+)
gotchaSeveral algorithms within the `opencv-contrib-python` package, particularly in modules like `xfeatures2d` (e.g., SIFT, SURF), were historically patent-encumbered. While some patents have expired, users should be aware of potential intellectual property concerns depending on their region and intended commercial use.fixBefore deploying applications using `contrib` modules in commercial products, verify the patent status of specific algorithms relevant to your deployment region. Consider alternative, patent-free algorithms (e.g., ORB) if intellectual property concerns are critical.
affects: All versions containing patent-affected algorithms (e.g., SIFT, SURF)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cv2'
The Python interpreter cannot find the OpenCV module, usually because the `opencv-contrib-python` package is not installed in the active Python environment or there's an environment mismatch.
fixEnsure you are in the correct Python environment and install the package: `pip install opencv-contrib-python`
AttributeError: module 'cv2' has no attribute 'xfeatures2d'
You are attempting to use features from the `xfeatures2d` module (e.g., SIFT, SURF), but either the `opencv-contrib-python` package is not installed (only `opencv-python` might be), or there's a version conflict.
fixUninstall any existing OpenCV installations and install `opencv-contrib-python`: `pip uninstall opencv-python opencv-contrib-python` then `pip install opencv-contrib-python`
error: (-213:The function/feature is not implemented) This algorithm is patented and is excluded in this configuration; Set OPENCV_ENABLE_NONFREE CMake option and rebuild the library
This error occurs when trying to use patented algorithms like SURF, which are not included in the pre-built `opencv-contrib-python` wheels due to licensing restrictions, even though the `xfeatures2d` module itself is available.
fixTo use patented algorithms, you must manually compile OpenCV from source, including the `opencv_contrib` modules and setting the CMake flag `OPENCV_ENABLE_NONFREE=ON` during the build process.
cv2.imshow() freezing or not displaying image
The `cv2.imshow()` function requires `cv2.waitKey()` to properly display a window and process events. Without it, the window may appear and immediately close, or the program might freeze as the event loop isn't handled.
fixAdd `cv2.waitKey(0)` (for images, waits indefinitely until a key is pressed) or `cv2.waitKey(1)` (for video streams, waits 1ms) after `cv2.imshow()` and `cv2.destroyAllWindows()` at the end of your script.
Upgrade
Version history
5.0.0.93latest on PyPI · released Jul 2, 2026
Audit
Dependencies
numpyrequiredOpenCV relies heavily on NumPy arrays for image and matrix data representation. While not always an explicit pip dependency, it's fundamental for all operations. Specific OpenCV versions are built against particular NumPy versions, leading to potential compatibility issues if versions are mismatched.