---
id: opencv-contrib-python-headless
version: "5.0.0.93"
license: Apache 2.0
license_treatment: permissive
maintenance: active
---

# opencv-contrib-python-headless — Wrapper package for OpenCV python bindings.

License: permissive · Maintenance: active · Downloads: 3.0M/mo

## 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 above — 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

pip install opencv-contrib-python-headless
uv add opencv-contrib-python-headless
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_current
- Install friction: medium
- Maintenance: active
- Downloads: 3.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

computer vision image processing, opencv headless server, image recognition detection, video processing algorithms, contrib modules opencv, headless opencv container, server image processing, computer-vision, headless-deployment, image-processing

[View on SkillFed](https://skillfed.io/packages/opencv-contrib-python-headless) · [View on PyPI](https://pypi.org/project/opencv-contrib-python-headless/)