opencv-python

opencv-python packages the official OpenCV computer-vision library as ready-to-install Python wheels, distributed in four variants (main or contrib modules, standard or headless) so pip install opencv-python gives you image and video processing, camera capture, object detection, and hundreds of other CV algorithms through the familiar cv2 module without ever touching CMake or a C++ compiler. The repository itself doesn’t contain OpenCV’s C++ source; it pulls in OpenCV, its contrib modules, and a cross-platform build toolchain as pinned git submodules, then compiles and packages them for every supported CPython version, OS, and architecture.

A CI pipeline built on GitHub Actions (covering Windows, macOS, and manylinux2014 Docker images) compiles OpenCV per Python version and build flavor, repairs the resulting wheel with auditwheel or delocate for portability, verifies that it imports cleanly, and publishes it to PyPI whenever a new tag is pushed. That plumbing is why opencv-python is the standard way most Python developers obtain OpenCV: no local compiling, releases tied directly to upstream OpenCV versions, and separate lightweight headless builds for servers and containers that don’t need GUI (Qt) dependencies.

What You Get

• Prebuilt cv2 wheels - pip install opencv-python installs a ready-compiled binary for your OS and Python version, no CMake or compiler required
• Four package variants - choose between main or contrib (extra) modules, and standard (GUI-enabled) or headless (no Qt/X11 dependencies) builds
• Bundled runtime dependencies - wheels ship FFmpeg for video I/O and, for non-headless Linux builds, Qt 5 for GUI windows like cv2.imshow
• Version-pinned numpy compatibility - build metadata pins compatible numpy ranges per Python version, avoiding common ABI-mismatch install failures
• Bundled Haar cascade data files - classifier XML files ship inside the package (cv2.data.haarcascades) for ready-to-use face and object detection

Common Use Cases

• Face and object detection - load bundled Haar cascades or DNN models to detect faces, eyes, or custom objects in images and video streams
• Video capture and processing pipelines - grab frames from a webcam or video file via cv2.VideoCapture and apply filters, transforms, or ML inference per frame
• Headless server-side image processing - install opencv-python-headless in Docker or cloud environments to resize, transform, or analyze images without pulling in GUI libraries
• Prototyping computer vision research - the same cv2 API used across tutorials and papers, available instantly via pip instead of a source build

Under The Hood

Architecture opencv-python is a packaging and CI orchestration repository, not the OpenCV C++ source itself: the actual computer-vision code lives in opencv and opencv_contrib, pulled in as pinned git submodules (see .gitmodules), while this repo’s setup.py (built on scikit-build/CMake via a custom _build_backend) and find_version.py script drive compiling those submodules into a Python extension, with cv2/ starting as an empty package skeleton (__init__.py, data/__init__.py) that CMake’s install step populates at build time. Three GitHub Actions workflows (build_wheels_windows.yml, build_wheels_manylinux.yml, build_wheels_macos.yml) run the full build matrix — main vs. contrib modules, GUI vs. headless — across every supported CPython version, with Linux builds executed inside docker/’s extended manylinux2014 images and patches/ applying repo-specific fixes to the vendored OpenCV sources before compilation. If the submodule-pinning or CMake-bootstrap layer changes, the entire packaging pipeline breaks, since every downstream step (wheel repair, testing, PyPI publish) assumes a successfully compiled OpenCV binary.

Tech Stack The build is orchestrated with scikit-build (skbuild) plus a custom backend-path build backend that installs CMake only if a compatible version isn’t already present, per pyproject.toml. Runtime dependencies are tightly version-pinned to numpy per Python release (numpy<2.0 for <3.9, exact pins like 2.0.2/2.1.3/2.3.2 for 3.9-3.14) to avoid ABI mismatches, and setuptools is capped below 70 for Python 3.12+ to keep the legacy build path working. Wheel portability comes from auditwheel on Linux and delocate on macOS, bundling shared-library dependencies like FFmpeg (LGPLv2.1, for video I/O) and, on non-headless Linux, Qt 5 (LGPLv3, for cv2.imshow-style GUI windows) directly into the wheel. CI/CD runs entirely on GitHub Actions, with multibuild (another pinned submodule) supplying shared build-matrix tooling across platforms.

Code Quality Because this repository doesn’t contain OpenCV’s own C++ implementation, there’s limited application code to assess for the usual craft signals — naming, error handling, type safety. What exists is a thin Python-side smoke-test suite in tests/test.py: two unittest cases confirming cv2 imports and that cv2.VideoCapture can open a bundled sample video, plus tests/get_build_info.py for printing OpenCV’s compiled build configuration. There’s a pylintrc in tests/, but no broader linting, static typing, or CI test gate beyond the README’s stated build-verification step (“test that Python can import the library and run some sanity checks”). Quality here is really about build reproducibility and wheel correctness across platforms rather than runtime code craft.

API Design There’s no bespoke API design to evaluate — importing cv2 gives users OpenCV’s own long-standing C++ API as auto-generated Python bindings, unmodified by this repository. This project’s actual contribution is developer experience around installation: it collapses what used to require a local OpenCV compile (a build that can take hours on constrained hardware, per the README) into a single pip install opencv-python, with four selectable variants (opencv-python, opencv-contrib-python, and their -headless counterparts) so users pick exactly the GUI/module footprint they need. That packaging convenience — reproducible per-platform wheels, submodule-pinned OpenCV versions, and headless builds for containers — is a widely used pattern, not a novel technical approach, but it solves a genuinely common pain point (cv2 import/DLL errors, slow source builds) that the project’s FAQ devotes significant space to.