OpenCV Contrib Python

4.13.0.92 · active · verified Thu Apr 09

opencv-contrib-python provides Python bindings for the full OpenCV library, including extra modules not available in the base `opencv-python` package due to licensing or stability reasons (e.g., SIFT, SURF). It enables advanced computer vision functionalities like object detection, image processing, and video analysis. The current version is 4.13.0.92, with frequent updates generally following the main OpenCV library release cycle.

Warnings

gotcha There 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.
Fix: Ensure 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.
gotcha OpenCV'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').
Fix: For 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.
breaking OpenCV 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.
Fix: Always 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.
gotcha Several 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.
Fix: Before 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.

Install

pip install opencv-contrib-python Install with pip

Imports

cv2
```
import cv2
```

Quickstart

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()

view raw JSON →