{"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":"python","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,"search_vec":"'4.13.0.92':83 'access':35 'avail':77 'bind':27 'c':95 'cadenc':89 'cloud':66 'comput':8,17,99 'computer-vis':98 'contain':69 'contrib':2,31,44,108 'current':80 'deep':105 'deep-learn':104 'depend':54 'deploy':67 'display':75 'docker':68 'embed':71 'extra':45 'follow':85 'frequent':87 'graphic':50 'gui':53 'headless':4,33,107 'ideal':60 'imag':102,110 'image-manipul':109 'image-process':101 'interfac':52 'learn':21,106 'librari':10,23,96 'like':55 'machin':20 'main':39 'major':93 'make':58 'manipul':111 'modul':41,46 'often':90 'open':6,15 'open-sourc':14 'opencv':1,5,30,40,94 'opencv-contrib-python-headless':29 'packag':28 'power':13 'process':65,103 'provid':34 'python':3,26,32 'qt':56 'releas':88,97 'server':63 'server-sid':62 'side':64 'softwar':22 'sourc':7,16 'specif':25 'system':72 'tie':91 'user':51 'version':82 'vision':9,18,100 'without':48","created_at":"2026-04-09T18:45:26.792310+00:00","updated_at":"2026-04-16T17:34:49.210309+00:00","problems":[{"fix":"Ensure only one OpenCV package is installed. First, uninstall all existing OpenCV packages: `pip uninstall opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless`. Then, install only the headless version: `pip install opencv-contrib-python-headless`. Also, verify your pip is up-to-date: `pip install --upgrade pip`.","cause":"This error occurs when the `cv2` module (OpenCV's Python binding) cannot be found by the Python interpreter. This often happens due to incorrect installation, conflicting OpenCV packages (e.g., having both `opencv-python` and `opencv-contrib-python-headless` installed), or issues with the Python environment (like not activating a virtual environment where it's installed).","error":"ModuleNotFoundError: No module named 'cv2'"},{"fix":"Install the correct Visual C++ Redistributable for Visual Studio 2015, 2017, 2019, or 2022 from Microsoft's website. For N editions of Windows, install the Media Feature Pack. Ensure your pip version is updated, and consider using a fresh virtual environment. If the issue persists, manually adding the path to OpenCV's DLLs or Python's DLL directory to the system PATH might be necessary.","cause":"This Windows-specific error indicates that Python cannot load the necessary Dynamic Link Libraries (DLLs) required by OpenCV. This is frequently due to missing Visual C++ Redistributables (specifically 2015-2019/2022) or other system dependencies like Windows Media Feature Pack, or conflicts with Python versions and environments.","error":"ImportError: DLL load failed while importing _cv2: The specified module could not be found."},{"fix":"If GUI functionality is required, uninstall `opencv-contrib-python-headless` and install `opencv-contrib-python` (or `opencv-python` for main modules only): `pip uninstall opencv-contrib-python-headless` followed by `pip install opencv-contrib-python`. If you must stay headless, use libraries like Matplotlib to display images for debugging or verification: `import matplotlib.pyplot as plt; plt.imshow(image); plt.show()`.","cause":"The `opencv-contrib-python-headless` package is specifically built without GUI components, meaning functions like `cv2.imshow()`, `cv2.waitKey()`, and `cv2.destroyAllWindows()` are intentionally not included. This error arises when attempting to use these GUI-related functions in a headless environment.","error":"AttributeError: module 'cv2' has no attribute 'imshow'"},{"fix":"Update your code to use the newer API. For example, `cv2.aruco.detectMarkers` has been replaced by instantiating an `ArucoDetector` object and then calling its `detectMarkers` method. `cv2.aruco.Dictionary_get` is replaced by `cv2.aruco.getPredefinedDictionary()`. The fix involves creating a `cv2.aruco.ArucoDetector` with a dictionary and parameters, then using `detector.detectMarkers(image)`.","cause":"This error typically occurs due to API changes in the OpenCV `aruco` module, especially in versions 4.7.0 and newer. Older code attempting to use functions like `cv2.aruco.detectMarkers` or `cv2.aruco.Dictionary_get` with a newer OpenCV version will fail.","error":"AttributeError: module 'cv2.aruco' has no attribute 'detectMarkers' OR 'Dictionary_get'"}],"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-headless/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}