{"id":1602,"library":"opencv-contrib-python","title":"OpenCV Contrib Python","description":"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.","status":"active","version":"4.13.0.92","language":"en","source_language":"en","source_url":"https://github.com/opencv/opencv-python","tags":["computer-vision","image-processing","video-processing","machine-learning"],"install":[{"cmd":"pip install opencv-contrib-python","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"OpenCV 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.","package":"numpy","optional":false}],"imports":[{"symbol":"cv2","correct":"import cv2"}],"quickstart":{"code":"import cv2\nimport numpy as np\n\n# Create a dummy image (black background with white text)\nimg = np.zeros((300, 500, 3), dtype=np.uint8)\ncv2.putText(img, \"Hello, OpenCV!\", (50, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)\n\n# Display the image\ncv2.imshow(\"Dummy Image\", img)\n\n# Wait indefinitely until a key is pressed\ncv2.waitKey(0)\n\n# Destroy all OpenCV windows\ncv2.destroyAllWindows()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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').","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially around NumPy 2.x transition (OpenCV 4.10.0.84 onwards for Python 3.9+)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions containing patent-affected algorithms (e.g., SIFT, SURF)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}