{"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":"python","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,"search_vec":"'4.13.0.92':55 'advanc':39 'analysi':50 'avail':20 'base':23 'bind':10 'comput':40,68 'computer-vis':67 'contrib':2,6 'current':52 'cycl':66 'detect':45 'due':28 'e.g':34 'enabl':38 'extra':17 'follow':60 'frequent':57 'full':13 'function':42 'general':59 'imag':46,71 'image-process':70 'includ':16 'learn':78 'librari':15,64 'licens':30 'like':43 'machin':77 'machine-learn':76 'main':62 'modul':18 'object':44 'opencv':1,5,14,25,63 'opencv-contrib-python':4 'opencv-python':24 'packag':27 'process':47,72,75 'provid':8 'python':3,7,9,26 'reason':33 'releas':65 'sift':35 'stabil':32 'surf':36 'updat':58 'version':53 'video':49,74 'video-process':73 'vision':41,69","created_at":"2026-04-09T03:55:10.867869+00:00","updated_at":"2026-04-16T17:34:37.204615+00:00","problems":[{"fix":"Ensure you are in the correct Python environment and install the package: `pip install opencv-contrib-python`","cause":"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.","error":"ModuleNotFoundError: No module named 'cv2'"},{"fix":"Uninstall any existing OpenCV installations and install `opencv-contrib-python`: `pip uninstall opencv-python opencv-contrib-python` then `pip install opencv-contrib-python`","cause":"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.","error":"AttributeError: module 'cv2' has no attribute 'xfeatures2d'"},{"fix":"To 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.","cause":"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.","error":"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"},{"fix":"Add `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.","cause":"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.","error":"cv2.imshow() freezing or not displaying image"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.0.0.93","cli_name":"","cli_version":null,"type":"library","homepage":"https://opencv.org","github":"https://github.com/opencv/opencv-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opencv-contrib-python/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}