opencv-contrib-python-headless

Wrapper package for OpenCV python bindings.

opencv-contrib-python-headless v5.0.0.93 3.0M downloads/30d#2,792 on PyPI★ 5,349

Permissive license Apache 2.0 Active released 2026-07-02

What it is and what it does

opencv-contrib-python-headless is a pre-built wheel distribution of OpenCV that includes both core and contrib (extra) modules, optimized for server and containerized environments where GUI functionality is not needed. It wraps OpenCV's C++ implementation with Python bindings, providing access to computer vision algorithms for image and video processing, feature detection, object recognition, and related tasks.

The package depends only on numpy and is designed to minimize container size and system dependencies by excluding GUI libraries. It supports Python 3.6 through 3.14 on Windows, macOS, and Linux, with platform-specific wheels for x86_64 and aarch64 architectures. The headless variant is recommended for any deployment that does not require display functions, or where another GUI framework is already in use.

Use it for:

Build Docker images for computer vision microservices without heavy GUI library dependencies
Process images and video streams in cloud functions or batch jobs on servers
Detect and recognize objects or features in automated image analysis pipelines
Extract and match keypoints or descriptors for image stitching or 3D reconstruction workflows
Perform real-time video frame processing in headless streaming or surveillance applications

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides OpenCV's computer vision algorithms and image processing functions in a headless (no GUI) package with contrib modules, designed for server and containerized environments.

Yes, if you need OpenCV's contrib modules in a server or container environment. The headless variant is the right choice for any non-GUI deployment, reducing image size and dependency complexity. Install friction is moderate but manageable with modern pip; maintenance is active and security record is clean. Choose this over standard packages when GUI functionality is not required.

Install

opencv-contrib-python-headless on PyPI

pip

pip install opencv-contrib-python-headless

uv

uv add opencv-contrib-python-headless

poetry

poetry add opencv-contrib-python-headless

Installing opencv-contrib-python-headless

Before you install

Medium install friction due to compiled C++ bindings and platform-specific wheels, but pre-built binaries for common platforms (x86_64, aarch64, Windows, macOS) reduce build complexity. Active maintenance with recent releases; requires pip >= 19.3 and may need system C++ runtime libraries on Windows.

License in practice

Apache 2.0 permissive license allows commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the license notice.

Quickstart

pip install opencv-contrib-python-headless
import opencv_contrib_python_headless
# Use with numpy for image processing tasks

On Windows, Visual C++ redistributable 2015 or later may be required; on older Windows versions, Universal C Runtime may also be needed. Requires pip >= 19.3 to install manylinux2014 wheels.

Verify before relying

Whether all contrib modules are fully functional in headless mode without GUI-dependent features
Performance characteristics compared to building from source with CUDA or other accelerators
Compatibility with non-standard Python implementations beyond CPython
Specific usage patterns and API surface for contrib modules in this distribution

Package facts

License	Apache 2.0 (permissive)
Python support	supports the current Python release (>=3.6)
Install friction	medium — platform-specific wheel
Runtime dependencies	1 — numpy
Maintenance	actively maintained — 43 days since the last release
Last repo commit	2026-07-28
First released	2018-07-23
Downloads	2,998,610/month — #2,792 on PyPI (30-day window, as of 2026-08-14)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-14)

Evidence: opencv_contrib_python_headless-5.0.0.93-cp37-abi3-macosx_13_0_arm64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-macosx_14_0_x86_64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-manylinux_2_28_aarch64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-manylinux_2_28_x86_64.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-win32.whl; opencv_contrib_python_headless-5.0.0.93-cp37-abi3-win_amd64.whl

Development Status :: 5 - Production/StableEnvironment :: ConsoleIntended Audience :: DevelopersIntended Audience :: EducationIntended Audience :: Information TechnologyIntended Audience :: Science/ResearchLicense :: OSI Approved :: Apache Software LicenseOperating System :: MacOSOperating System :: Microsoft :: WindowsOperating System :: POSIXOperating System :: UnixProgramming Language :: C++Programming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.6Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonTopic :: Scientific/EngineeringTopic :: Scientific/Engineering :: Image RecognitionTopic :: Software Development