{"id":670,"library":"opencv-python-headless","title":"OpenCV Python Headless","description":"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.","status":"active","version":"4.13.0.92","language":"python","source_language":"en","source_url":"https://github.com/opencv/opencv-python","tags":["computer vision","image processing","AI","headless","server-side","machine learning"],"install":[{"cmd":"pip install opencv-python-headless","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"OpenCV heavily relies on NumPy arrays for image and video data representation and manipulation.","package":"numpy","optional":false}],"imports":[{"note":"OpenCV Python bindings are consistently imported under the 'cv2' namespace, regardless of the installed package (opencv-python or opencv-python-headless).","wrong":"import opencv-python-headless","symbol":"cv2","correct":"import cv2"}],"quickstart":{"code":"import cv2\nimport numpy as np\nimport os\n\n# Create a dummy image (e.g., 100x100 white image)\ndummy_image_path = 'dummy_image.png'\nimg = np.zeros((100, 100, 3), dtype=np.uint8)\nimg.fill(255) # White image\n\n# Save the dummy image\ncv2.imwrite(dummy_image_path, img)\n\n# Read the image\nimage = cv2.imread(dummy_image_path)\n\nif image is not None:\n    print(f\"Image loaded successfully with shape: {image.shape}\")\n    \n    # Convert to grayscale\n    gray_image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)\n    \n    # Apply a simple blur\n    blurred_image = cv2.GaussianBlur(gray_image, (5, 5), 0)\n    \n    # Save the processed image (e.g., 'processed_image.png')\n    output_path = 'processed_image.png'\n    cv2.imwrite(output_path, blurred_image)\n    print(f\"Processed image saved to {output_path}\")\n    \n    # Clean up dummy image\n    os.remove(dummy_image_path)\n    os.remove(output_path)\nelse:\n    print(\"Error: Could not load image.\")","lang":"python","description":"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()`."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"4.10.0.82 and later (for Python >=3.9), or older versions with newer NumPy"},{"fix":"Upgrade your pip installer to the latest version before attempting to install: `pip install --upgrade pip`.","message":"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.","severity":"gotcha","affected_versions":"4.3.0 and later"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<4.8.1.78"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.10.0.82"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"4.13.0.90"},{"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`.","message":"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'.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T17:41:47.990Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'cv2'"},{"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).","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.","error":"ImportError: libGL.so.1: cannot open shared object file: No such file or directory"},{"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).","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.","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'"},{"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`.","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.","error":"AttributeError: module 'cv2' has no attribute 'face' (or 'dnn', 'ximgproc', etc.)"}],"ecosystem":"pypi","meta_description":null,"install_score":50,"install_tag":"draft","quickstart_score":30,"quickstart_tag":"draft","pypi_latest":"4.13.0.92","install_checks":{"last_tested":"2026-05-12","tag":"draft","tag_description":"notable install failures or slow imports","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.2,"import_time_s":0.27,"mem_mb":8.3,"disk_size":"243M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":8.3,"disk_size":"243M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5,"import_time_s":0.36,"mem_mb":8.6,"disk_size":"249M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":8.6,"disk_size":"249M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.9,"import_time_s":0.34,"mem_mb":8.4,"disk_size":"238M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":8.4,"disk_size":"238M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5,"import_time_s":0.34,"mem_mb":8.8,"disk_size":"237M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":8.8,"disk_size":"237M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.2,"import_time_s":0.23,"mem_mb":8.1,"disk_size":"253M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":8.1,"disk_size":"253M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"draft","tag_description":"notable failures across runtimes","results":[{"runtime":"python:3.10-alpine","exit_code":-1},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":-1},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":-1},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":-1},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":-1},{"runtime":"python:3.9-slim","exit_code":0}]}}