OpenCV Contrib Python Headless

4.13.0.92 · active · verified Thu Apr 09

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.

Warnings

breaking 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.
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.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.
breaking 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.
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`.
gotcha 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.
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.

Install

pip install opencv-contrib-python-headless Install latest version

Imports

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.

Quickstart

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.

view raw JSON →