Registry /
ai-ml / opencv-contrib-python-headless
Install & Compatibility
Where this runs
tested against v5.0.0.93 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.322s · 257MB
258MB installed
● package 258MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cv2
✓ import cv2
✗ from cv2 import cv2
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.
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.
import cv2
import numpy as np
# Create a dummy image (e.g., a black 100x100 pixel image)
# In a headless environment, you would typically load an image from disk or a stream
image = np.zeros((100, 100, 3), dtype=np.uint8)
# Perform a simple operation: draw a white rectangle
cv2.rectangle(image, (20, 20), (80, 80), (255, 255, 255), -1)
# Convert image to grayscale
grayscale_image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
# Print image properties (no GUI interaction)
print(f"OpenCV Version: {cv2.__version__}")
print(f"Original Image Shape: {image.shape}")
print(f"Grayscale Image Shape: {grayscale_image.shape}")
# Example of using a contrib module (if applicable and available in this build)
# Note: Not all contrib features are guaranteed to be present or stable.
# For example, SIFT/SURF are in contrib and often patented/non-free. We'll use a simpler one.
# Example: Feature2D algorithms are common in contrib.
# This specific example might not run without a specific image for feature detection
# For simplicity, we'll stick to basic operations for quickstart.
Debug
Known issues
breakingThis '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.fixUse 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.
affects: All versions of `opencv-contrib-python-headless`
breakingVersion 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.fixThis 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.
affects: 4.13.0.90
gotchaDo 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.fixIf 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.
affects: All versions
gotchaNumPy 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.fixIt'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.
affects: All versions, particularly when upgrading Python or NumPy independently.
breakingOpenCV 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.fixReview 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`.
affects: Migrating from OpenCV 3.x or older to 4.x
gotchaThis 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.fixBe 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.
affects: All versions using contrib features
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cv2'
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).
fixEnsure 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`.
ImportError: DLL load failed while importing _cv2: The specified module could not be found.
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.
fixInstall 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.
AttributeError: module 'cv2' has no attribute 'imshow'
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.
fixIf 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()`.
AttributeError: module 'cv2.aruco' has no attribute 'detectMarkers' OR 'Dictionary_get'
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.
fixUpdate 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)`.
Upgrade
Version history
5.0.0.93latest on PyPI · released Jul 2, 2026
Audit
Dependencies
numpyrequiredOpenCV's Python bindings extensively use NumPy arrays for image representation and matrix operations.