OpenCV Python Headless

raw JSON →
4.13.0.92 verified Tue May 12 auth: no python install: draft quickstart: draft

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.

pip install opencv-python-headless

Common errors

error ModuleNotFoundError: No module named 'cv2' ↓
cause This error often occurs when OpenCV is not installed correctly, or there are conflicting OpenCV packages (e.g., `opencv-python` and `opencv-python-headless`) installed in the same environment, or the Python interpreter cannot find the installed `cv2` module.
fix
Ensure only one OpenCV package is installed. Uninstall all conflicting packages (pip uninstall opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless) and then install only the desired headless version: pip install opencv-python-headless.
error ImportError: libGL.so.1: cannot open shared object file: No such file or directory ↓
cause This error typically arises in headless environments (like Docker containers or cloud servers) when the `opencv-python` package (which has GUI dependencies) is installed instead of `opencv-python-headless`, and the required OpenGL libraries are missing from the system.
fix
Replace opencv-python with opencv-python-headless in your requirements.txt or directly via pip uninstall opencv-python && pip install opencv-python-headless. If using a Linux distribution, you might also need to install libgl1-mesa-glx via your system's package manager (e.g., sudo apt-get update && sudo apt-get install -y libgl1-mesa-glx for Debian/Ubuntu based systems).
error cv2.error: OpenCV(4.x.x) (...) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. in function 'cvShowImage' ↓
cause This error happens when attempting to use GUI-related functions like `cv2.imshow()`, `cv2.waitKey()`, or `cv2.destroyAllWindows()` with `opencv-python-headless`. The headless version is intentionally compiled without GUI support to reduce dependencies and size for server-side or non-GUI environments.
fix
If GUI functionality is needed, switch to opencv-python (uninstall opencv-python-headless first: pip uninstall opencv-python-headless && pip install opencv-python). If in a headless environment, avoid GUI functions or use alternative methods for displaying images (e.g., saving to file, sending over network, or using libraries like Matplotlib for plotting and saving).
error AttributeError: module 'cv2' has no attribute 'face' (or 'dnn', 'ximgproc', etc.) ↓
cause This indicates that you are trying to use a module or function (like `cv2.face`, `cv2.dnn`, or `cv2.ximgproc`) that is part of OpenCV's 'contrib' (extra) modules, but you have installed the basic `opencv-python-headless` package, which only includes the main modules.
fix
Uninstall opencv-python-headless and install the headless version that includes the contrib modules: pip uninstall opencv-python-headless && pip install opencv-contrib-python-headless.

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`.
breaking Installing `opencv-python-headless` (and other `opencv-python` variants) on Alpine Linux environments will typically fail during the build process. `pip` will attempt to compile the package from source if no pre-built `manylinux` wheel is available for Alpine. This source compilation requires build tools like CMake, Ninja/Make, and a C/C++ compiler (e.g., GCC), which are often missing in minimal Alpine images and cannot be installed by `scikit-build`'s automatic dependency resolution. The build log explicitly states 'scikit-build could not get a working generator for your system' and 'Building Linux wheels... requires a compiler (e.g gcc). But scikit-build does *NOT* know how to install it on alpine'. ↓
fix Avoid installing on Alpine Linux if possible. Instead, use a `manylinux`-compatible base image (e.g., Debian-based `python:3.13-slim-bookworm` or `ubuntu:latest`) where pre-built `opencv-python-headless` wheels can be directly installed without compilation. If an Alpine environment is strictly necessary, ensure all required build dependencies like `cmake`, `build-base` (which includes GCC and make), and `ninja` are manually installed via `apk add` *before* attempting `pip install`.

Install compatibility draft last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) build_error - - - -
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 5.2s 0.27s 243M
3.10 slim (glibc) - - 0.17s 243M
3.11 alpine (musl) build_error - - - -
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 5.0s 0.36s 249M
3.11 slim (glibc) - - 0.29s 249M
3.12 alpine (musl) build_error - - - -
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 4.9s 0.34s 238M
3.12 slim (glibc) - - 0.30s 238M
3.13 alpine (musl) build_error - - - -
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 5.0s 0.34s 237M
3.13 slim (glibc) - - 0.30s 237M
3.9 alpine (musl) build_error - - - -
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 6.2s 0.23s 253M
3.9 slim (glibc) - - 0.19s 253M

Imports

Quickstart draft last tested: 2026-04-24

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.")
last verified Tue May 12
next check Fri Jun 26