{"id":2145,"library":"opencv-contrib-python-headless","title":"OpenCV Contrib Python Headless","description":"OpenCV (Open Source Computer Vision Library) is a powerful, open-source computer vision and machine learning software library. This specific Python binding package, `opencv-contrib-python-headless`, provides access to both the main OpenCV modules and the 'contrib' (extra) modules, but without any graphical user interface (GUI) dependencies like Qt. This makes it ideal for server-side processing, cloud deployments, Docker containers, and embedded systems where no display is available. It is currently at version 4.13.0.92 and follows a frequent release cadence, often tied to major OpenCV C++ library releases.","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","deep-learning","headless","contrib","image-manipulation"],"install":[{"cmd":"pip install opencv-contrib-python-headless","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"OpenCV's Python bindings extensively use NumPy arrays for image representation and matrix operations.","package":"numpy"}],"imports":[{"note":"The primary module for OpenCV in Python is `cv2`. Direct import of `cv2.cv2` was a common pattern in older versions or specific build environments but is incorrect for standard usage.","wrong":"from cv2 import cv2","symbol":"cv2","correct":"import cv2"}],"quickstart":{"code":"import cv2\nimport numpy as np\n\n# Create a dummy image (e.g., a black 100x100 pixel image)\n# In a headless environment, you would typically load an image from disk or a stream\nimage = np.zeros((100, 100, 3), dtype=np.uint8)\n\n# Perform a simple operation: draw a white rectangle\ncv2.rectangle(image, (20, 20), (80, 80), (255, 255, 255), -1)\n\n# Convert image to grayscale\ngrayscale_image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)\n\n# Print image properties (no GUI interaction)\nprint(f\"OpenCV Version: {cv2.__version__}\")\nprint(f\"Original Image Shape: {image.shape}\")\nprint(f\"Grayscale Image Shape: {grayscale_image.shape}\")\n\n# Example of using a contrib module (if applicable and available in this build)\n# Note: Not all contrib features are guaranteed to be present or stable.\n# For example, SIFT/SURF are in contrib and often patented/non-free. We'll use a simpler one.\n# Example: Feature2D algorithms are common in contrib.\n# This specific example might not run without a specific image for feature detection\n# For simplicity, we'll stick to basic operations for quickstart.\n","lang":"python","description":"This quickstart demonstrates basic image manipulation in a headless environment. It creates a dummy image, performs a rectangle drawing and grayscale conversion, and prints image properties. It explicitly avoids GUI functions like `cv2.imshow()` which are not available in the headless build."},"warnings":[{"fix":"Use alternative methods for image output (e.g., saving to file using `cv2.imwrite()` for common formats, converting to bytes for API responses) or use a different OpenCV package (`opencv-contrib-python`) if GUI is required. Ensure your environment does not inadvertently try to connect to an X server.","message":"This 'headless' package specifically excludes GUI functionality. Functions like `cv2.imshow()`, `cv2.waitKey()`, `cv2.imwrite()` (for some formats requiring GUI backends), and others that rely on windowing systems (like X11/Qt) will not work and may raise errors.","severity":"breaking","affected_versions":"All versions of `opencv-contrib-python-headless`"},{"fix":"This issue was resolved in the follow-up release `4.13.0.92`. Users on affected versions should upgrade to `4.13.0.92` or later. Alternatively, installing `libxcb1` on the system could serve as a temporary workaround for 4.13.0.90.","message":"Version 4.13.0.90 of `opencv-python-headless` (and thus `opencv-contrib-python-headless`) introduced an accidental dependency on `libxcb.so.1` on Linux, which is part of X11 libraries. This caused import failures in truly headless environments.","severity":"breaking","affected_versions":"4.13.0.90"},{"fix":"If multiple packages are installed, uninstall all of them (`pip uninstall opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless`) and then reinstall only the single desired package for your environment.","message":"Do NOT install multiple different OpenCV Python packages (e.g., `opencv-python`, `opencv-contrib-python`, `opencv-python-headless`, `opencv-contrib-python-headless`) in the same Python environment. They all use the same `cv2` namespace, leading to conflicts and unpredictable behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It's generally recommended to let the OpenCV pip package install its preferred NumPy version. If issues arise, try upgrading both `opencv-contrib-python-headless` and `numpy` to their latest compatible versions in a fresh virtual environment. Check OpenCV release notes for specific NumPy compatibility ranges if troubleshooting.","message":"NumPy version compatibility can be a common issue. OpenCV's Python bindings are compiled against specific NumPy versions. Incompatible NumPy versions can lead to `ImportError` or runtime crashes.","severity":"gotcha","affected_versions":"All versions, particularly when upgrading Python or NumPy independently."},{"fix":"Review the official OpenCV migration guides and changelogs. Code written for older versions may require updates to function calls, argument order, and data structures. For example, `xfeatures2d` modules typically require `opencv_contrib`.","message":"OpenCV 4.x introduced significant API changes compared to 2.x and 3.x, including the removal of many C API functions and structures, reorganization of modules (some moved to `opencv_contrib`), and changes in function signatures (e.g., `findContours` returning a pair instead of a triple in Python bindings). OpenCV now requires C++17.","severity":"breaking","affected_versions":"Migrating from OpenCV 3.x or older to 4.x"},{"fix":"Be aware that using `contrib` modules might involve additional licensing considerations or stability concerns. Refer to OpenCV documentation for specific `contrib` module usage patterns and any associated requirements. Always test thoroughly when relying on `contrib` features.","message":"This package includes 'contrib' (extra) modules. While these offer advanced functionalities (like SIFT, SURF, some machine learning algorithms), they may sometimes be less stable, less well-tested, or include patented/non-free algorithms compared to the main modules. Some `contrib` algorithms (e.g., `xfeatures2d`) require explicit import or different instantiation patterns.","severity":"gotcha","affected_versions":"All versions using contrib features"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}