OpenCV Python Headless

4.13.0.92 · active · verified Sat Mar 28

opencv-python-headless is a wrapper package for OpenCV (Open Source Computer Vision Library) Python bindings, specifically compiled without graphical user interface (GUI) support. This makes it ideal for server-side processing, cloud deployments, Docker containers, and other headless environments where displaying images or videos directly is not required. It provides core computer vision functionalities and is currently at version 4.13.0.92, with regular releases aligning with OpenCV's main development cycle.

Warnings

gotcha This 'headless' package specifically excludes GUI functionality. Functions like `cv2.imshow()`, `cv2.waitKey()`, and `cv2.destroyAllWindows()` are not available and will raise errors or cause runtime issues in environments lacking X server dependencies.
Fix: Use `opencv-python` instead of `opencv-python-headless` if GUI features are needed. For headless environments, perform image processing and save results to file, or use alternative display methods (e.g., web-based streaming) outside of OpenCV's GUI modules.
breaking Installing multiple OpenCV packages (e.g., `opencv-python` and `opencv-python-headless`, or any `opencv-contrib-python*` variant) in the same Python environment will lead to import conflicts and runtime errors because they all use the `cv2` namespace. Only one should be installed at a time.
Fix: Uninstall all OpenCV-related packages (`pip uninstall opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless`) and then install only the single desired package for your environment (e.g., `pip install opencv-python-headless`).
gotcha OpenCV's NumPy dependency has version-specific requirements. From OpenCV 4.10.0.82/84 onwards, packages for Python 3.9+ are built with NumPy 2.x support. Older Python versions or OpenCV builds might require NumPy 1.x. Mismatched NumPy versions can cause `ImportError` or runtime crashes.
Fix: Ensure your NumPy version is compatible with your `opencv-python-headless` and Python version. For Python 3.9+ with recent OpenCV, use `numpy>=2`. For older setups, ensure `numpy<2`.
gotcha Installation of `opencv-python-headless` (and other `opencv-python` variants) relies on `manylinux2014` wheels since OpenCV 4.3.0. If your `pip` version is older than 19.3, it may fail to install these wheels correctly, sometimes attempting a long, failing source build.
Fix: Upgrade your pip installer to the latest version before attempting to install: `pip install --upgrade pip`.
breaking Versions of `opencv-python-headless` prior to `4.8.1.78` are vulnerable to CVE-2023-4863, a critical heap-based buffer overflow in the bundled `libwebp` library. This vulnerability can lead to remote code execution when processing specially crafted WebP images.
Fix: Update `opencv-python-headless` to version `4.8.1.78` or newer to incorporate the patched `libwebp` library: `pip install --upgrade opencv-python-headless`.
gotcha Support for Python's `pathlib.Path` objects in functions like `cv2.imread()` and `cv2.imwrite()` was introduced in later versions (e.g., around 4.10.0.82/84). In older versions, passing a `Path` object directly will result in a `TypeError`; you must convert it to a string explicitly.
Fix: Convert `pathlib.Path` objects to strings using `str(my_path_object)` before passing them to OpenCV functions if using older versions. Upgrade to `4.10.0.82` or later for direct `Path` object support.
gotcha The 4.13.0.90 release (and potentially other minor 4.13.0.x versions before .92) had an X server dependency issue that could prevent it from running in truly headless environments. Version 4.13.0.92 specifically addresses this problem.
Fix: If experiencing issues in a headless environment with 4.13.0.90, upgrade to 4.13.0.92: `pip install opencv-python-headless==4.13.0.92`.

Install

pip install opencv-python-headless Install latest version

Imports

cv2
```
import cv2
```
OpenCV Python bindings are consistently imported under the 'cv2' namespace, regardless of the installed package (opencv-python or opencv-python-headless).

Quickstart

This quickstart demonstrates basic image processing in a headless environment. It creates a dummy image, reads it using `cv2.imread()`, converts it to grayscale, applies a Gaussian blur, and then saves the result using `cv2.imwrite()`. This sequence avoids GUI-dependent functions like `cv2.imshow()`.

import cv2
import numpy as np
import os

# Create a dummy image (e.g., 100x100 white image)
dummy_image_path = 'dummy_image.png'
img = np.zeros((100, 100, 3), dtype=np.uint8)
img.fill(255) # White image

# Save the dummy image
cv2.imwrite(dummy_image_path, img)

# Read the image
image = cv2.imread(dummy_image_path)

if image is not None:
    print(f"Image loaded successfully with shape: {image.shape}")
    
    # Convert to grayscale
    gray_image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    
    # Apply a simple blur
    blurred_image = cv2.GaussianBlur(gray_image, (5, 5), 0)
    
    # Save the processed image (e.g., 'processed_image.png')
    output_path = 'processed_image.png'
    cv2.imwrite(output_path, blurred_image)
    print(f"Processed image saved to {output_path}")
    
    # Clean up dummy image
    os.remove(dummy_image_path)
    os.remove(output_path)
else:
    print("Error: Could not load image.")

view raw JSON →