opencv-python

Distributes pre-compiled OpenCV Python bindings as binary wheels across Windows (x86_64, x86), Linux (x86_64, i686, aarch64), and macOS (x86_64, arm64) for Python 3.7-3.12, eliminating the need for developers to compile OpenCV from source. Uses manylinux2014 standard for Linux wheels to ensure compatibility across diverse distributions. The build system automatically manages git submodules to pull the correct OpenCV C++ source version, compiles it with platform-specific optimizations, and packages the resulting extension modules into distributable wheels via a custom pyproject.toml backend.

Provides four distinct package variants (opencv-python, opencv-contrib-python, opencv-python-headless, opencv-contrib-python-headless) allowing developers to select the exact feature set and dependencies needed for their deployment context. The build system conditionally includes GUI components (Qt 5, X11 libraries) only in non-headless variants, and conditionally includes contrib modules (extra algorithms, experimental features) only in -contrib variants. This is managed through CMake configuration flags passed during the C++ compilation stage, reducing final wheel size and dependency footprint by 30-40% for headless deployments.

Builds separate wheels for each supported Python version (3.7, 3.8, 3.9, 3.10, 3.11, 3.12) by compiling against version-specific Python headers and ABI (Application Binary Interface). The build system detects the Python version during compilation and generates extension modules with the correct ABI tag (e.g., cp39 for CPython 3.9). The CI/CD pipeline maintains separate build jobs for each Python version, ensuring that wheels are compatible with their target Python interpreter. This approach avoids ABI incompatibilities that would occur if a single wheel were used across multiple Python versions, which have different memory layouts and API signatures.

Implements a four-part versioning scheme (cv_major.cv_minor.cv_revision.package_revision) that decouples OpenCV upstream versions from packaging-specific revisions. For example, 4.8.0.2 indicates OpenCV 4.8.0 with package revision 2 (second packaging iteration). Development builds append git hash identifiers (e.g., 4.8.0+abc1234) to enable tracking of unreleased builds. This allows maintainers to issue packaging fixes, dependency updates, or platform-specific patches without waiting for upstream OpenCV releases, while maintaining clear traceability to the underlying OpenCV version.

Implements a custom Python build backend (in _build_backend/backend.py) that extends PEP 517 standards to orchestrate complex multi-stage compilation. The backend manages git submodule initialization, invokes CMake to configure the OpenCV C++ build with platform-specific flags, compiles extension modules via setuptools, and packages results into wheels. This abstraction allows setup.py to remain relatively simple while delegating platform-specific logic (Windows MSVC vs Unix Makefiles, architecture detection, dependency resolution) to the backend. The backend also handles patching of OpenCV source code before compilation, enabling fixes or customizations without forking the upstream repository.

Maintains the OpenCV C++ source code as a git submodule, allowing the opencv-python repository to pin exact OpenCV versions without duplicating source code. When a new OpenCV release is made, maintainers manually update the submodule reference to point to the new tag/commit. The build system automatically initializes and checks out the submodule during the build process, ensuring reproducible builds across different machines and CI/CD environments. This approach decouples the opencv-python release cycle from OpenCV's, allowing packaging updates or patches to be released independently.

Implements an automated CI/CD pipeline (documented in CI/CD Pipeline section) that builds wheels across 3 major operating systems (Windows, macOS, Linux), 5+ CPU architectures (x86_64, x86, i686, aarch64, arm64), and 6 Python versions (3.7-3.12) in parallel. Each platform has a dedicated workflow (Linux Build Workflow, macOS Build Workflow, Windows Build Workflow) that handles platform-specific build steps, compiler selection, and dependency installation. The pipeline automatically triggers on new OpenCV releases (via submodule updates) and packaging changes, runs basic smoke tests on built wheels, and publishes successful builds to PyPI. Docker build environments ensure consistent compilation across different CI/CD runners.

Builds headless package variants by passing CMake flags that exclude GUI-related dependencies (Qt 5, X11 libraries, GTK) during the C++ compilation stage. The build backend detects the target variant (via environment variables or setup.py configuration) and conditionally invokes CMake with -DBUILD_SHARED_LIBS=OFF, -DWITH_QT=OFF, and similar flags. This results in significantly smaller wheels (30-40% reduction) and eliminates transitive dependencies on heavy GUI libraries, making headless variants ideal for Docker containers, serverless functions, and cloud deployments where GUI functionality is unnecessary. The Python bindings remain functionally identical except for GUI-specific functions (cv2.imshow, cv2.waitKey) which raise NotImplementedError.

Builds Linux wheels using the manylinux2014 standard (PEP 599), which targets glibc 2.17 and older, ensuring compatibility across CentOS 7, Ubuntu 14.04+, Debian 8+, and most modern Linux distributions. The build system uses Docker containers with manylinux2014 base images to compile against the correct glibc version and system libraries, then uses auditwheel to verify and repair wheels by bundling necessary shared libraries (libstdc++, libgomp) into the wheel. This approach eliminates the need for users to have specific system libraries installed, making wheels portable across diverse Linux environments without requiring source compilation.

Manages licensing for bundled third-party binaries (FFmpeg, Qt 5, and others) by including a LICENSE-3RD-PARTY.txt file in distributions that lists all licenses and their terms. FFmpeg is included in all wheels under LGPLv2.1, Qt 5 is included in non-headless Linux wheels under LGPLv3, and other binaries have their respective licenses documented. The build system automatically bundles these binaries during compilation and ensures license files are included in the final wheel. This approach provides legal transparency and ensures compliance with open-source licensing requirements, particularly important for commercial users who need to understand licensing obligations.

Builds separate wheels for each supported CPU architecture (x86, x86_64, i686, aarch64, arm64) by detecting the target architecture during the build process and passing architecture-specific compiler flags to CMake. The CI/CD pipeline maintains separate build jobs for each architecture, with aarch64 and arm64 builds running on appropriate runners (e.g., AWS Graviton instances for aarch64, Apple Silicon for arm64). This enables users to install architecture-native wheels that are optimized for their specific CPU, improving performance through architecture-specific SIMD instructions and memory layouts. The build system automatically selects the correct wheel during pip install based on the runtime Python interpreter's architecture.