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.1s · import 0.284s · 238MB
240MB installed
● package 240MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cv2
✓ import cv2
✗ import opencv-python-headless
OpenCV Python bindings are consistently imported under the 'cv2' namespace, regardless of the installed package (opencv-python or opencv-python-headless).
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.")
Debug
Known issues
gotchaThis '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.fixUse `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.
affects: All versions
breakingInstalling 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.fixUninstall 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`).
affects: All versions
gotchaOpenCV'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.fixEnsure 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`.
affects: 4.10.0.82 and later (for Python >=3.9), or older versions with newer NumPy
gotchaInstallation 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.fixUpgrade your pip installer to the latest version before attempting to install: `pip install --upgrade pip`.
affects: 4.3.0 and later
breakingVersions 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.fixUpdate `opencv-python-headless` to version `4.8.1.78` or newer to incorporate the patched `libwebp` library: `pip install --upgrade opencv-python-headless`.
affects: <4.8.1.78
gotchaSupport 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.fixConvert `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.
affects: <4.10.0.82
gotchaThe 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.fixIf 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`.
affects: 4.13.0.90
breakingInstalling `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'.fixAvoid 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`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cv2'
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.
fixEnsure 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`.
ImportError: libGL.so.1: cannot open shared object file: No such file or directory
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.
fixReplace `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).
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'
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.
fixIf 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).
AttributeError: module 'cv2' has no attribute 'face' (or 'dnn', 'ximgproc', etc.)
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.
fixUninstall `opencv-python-headless` and install the headless version that includes the contrib modules: `pip uninstall opencv-python-headless && pip install opencv-contrib-python-headless`.
Upgrade
Version history
5.0.0.93latest on PyPI · released Jul 2, 2026
Audit
Dependencies
numpyrequiredOpenCV heavily relies on NumPy arrays for image and video data representation and manipulation.