opencv-python: prebuilt OpenCV wheels and how to pick the right one

What opencv-python actually packages, and who it is for

OpenCV itself is a C++ computer vision library. The opencv-python repository is not a fork of it: it is an automated CI toolchain that produces precompiled Python wheels named opencv-python, opencv-python-headless, opencv-contrib-python and opencv-contrib-python-headless. The README states that these are pre-built CPU-only OpenCV packages for Python, and that the wheel already contains statically built OpenCV binaries, so installing OpenCV separately is unnecessary.

That last point decides the audience. If your work is image loading, filtering, feature detection, calibration or running a model through cv2.dnn on CPU, a wheel gets you there in one command. If you need CUDA, the README is explicit that you should check the manual build section to compile the bindings from source and enable additional modules. There is no wheel flag that turns CUDA on.

The contrib variants are the other axis. opencv-contrib-python contains both main modules and the contrib/extra modules, and the README points readers at the OpenCV documentation for the contrib listing rather than enumerating it. So the choice is two binary decisions: headless or not, contrib or not. Four packages, one namespace.

One namespace, four packages: why installing two breaks the environment

All four distributions import as cv2. The README states plainly that there is no plugin architecture and that all the packages use the same namespace, which means pip will happily install two of them into the same environment and you will get whichever files land last. The instruction is to select only one, and if you have already mixed them, to run pip uninstall on all of them and reinstall a single package.

The same warning covers manual installs. If a cv2 module or cv2.so already sits in the root of site-packages from an older non-pip installation, the README says to remove it before installing to avoid conflicts. This is a common source of the vague import errors the FAQ addresses.

The headless split is the part worth understanding rather than memorising. The headless packages are not compiled with Qt or other GUI components, so they avoid a dependency chain to X11 libraries and produce smaller Docker images. The trade-off is that cv2.imshow and friends are gone. If you draw windows with PyQt or another toolkit and only use OpenCV for processing, headless is the correct pick; if you call cv2.imshow directly, it is the wrong one.

Installing opencv-python and a first real use

The README lists pip version 19.3 as the minimum supported. Step one is therefore upgrading pip, because Linux distributions in particular ship older versions, and the FAQ ties old pip directly to a confusing failure: pip does not recognise manylinux2014 wheels, falls back to the source distribution introduced in 4.3.0.38, and that build then dies with ModuleNotFoundError: No module named 'skbuild'.

pip install --upgrade pip
pip -V

With pip current, install exactly one package. For a desktop machine where you want the standard modules and will display images:

pip install opencv-python

For a server, container or any environment without GUI libraries, use the headless variant instead. This is the package to reach for in a Dockerfile, since the README notes it drops the X11 dependency chain:

pip install opencv-python-headless

Import and confirm the build works. The README gives the Haar cascade example below, and notes that cv2.data.haarcascades is a shortcut to the bundled data folder. All four packages ship the cascade files.

import cv2

print(cv2.__version__)
classifier = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
)
print(classifier.empty())

If classifier.empty() returns False, the library loaded and found its data. If the import itself fails on Windows with a DLL load error, the FAQ's first remedy is installing the Visual C++ redistributable 2015; Windows N and KN editions additionally need the Media Feature Pack, and Windows Server 2012+ needs the Media Foundation feature enabled in Server Manager. The README warns against the Windows Server Essentials Media Pack, which pulls in a role that changes server configuration.

What the wheels leave out, and when to build from source instead

CPU-only is a hard boundary, not a default you can override at runtime. The README's manual build section exists precisely for users who want additional modules such as CUDA, and the build is driven by scikit-build: pyproject.toml declares scikit-build>=0.14.0 among the build requirements and uses a custom backend in _build_backend to manage the CMake check and installation.

setup.py shows how the variants are produced, which is also a map of what you lose by taking a wheel. Environment variables named contrib, headless, java and rolling are read at build time, and the source directory is opencv, with submodules for opencv_contrib and opencv_extra present in the repository. Java bindings, for instance, are built only when the java variable is set. None of that is reachable from a pip install.

There is a packaging wrinkle worth knowing because it affects anyone pinning dependencies. pyproject.toml selects different NumPy versions per Python release: numpy<2.0 below Python 3.9, numpy==2.0.2 for 3.9 through 3.12, numpy==2.1.3 for 3.13 and numpy==2.3.2 for 3.14. setup.py sets install_requires with numpy<2.0 for Python below 3.9 and numpy>=2 from 3.9 upward. A dependency resolver that insists on an older NumPy in a modern interpreter will fight the wheel's own requirements.

The repository also carries patch_auditwheel_whitelist.py and a patches directory, plus a multibuild submodule and travis_* scripts. That is the machinery that makes the wheels installable across manylinux, macOS and Windows, and it is the reason the project is best understood as a build system rather than a library.

opencv-python vs opencv-python-headless, and what a source build gives you

The most useful comparison is internal, because the headless split is the decision most users get wrong. opencv-python links GUI components; opencv-python-headless does not. The README frames headless as the choice for server environments such as Docker and cloud, and notes the smaller images that follow from avoiding the X11 chain. The cost is cv2.imshow and the window functions. Nothing else about the processing API changes.

The external alternative is building OpenCV yourself, which is not a different library but a different distribution channel. The README's manual build section covers compiling the bindings from source, and a separate section covers manual debug builds and source distributions. The difference in approach is stark: a wheel is a fixed artifact built by CI with the contrib, headless, java and rolling flags fixed at build time, while a source build lets you set those flags and add CUDA. You pay for it in build time, toolchain setup and the need to keep the build working across Python upgrades.

A middle path exists in the repository itself. The README documents development builds and manylinux wheels, and the release history shows a rolling 5.0.0.93 release alongside 4.14.0.94 and 4.13.0.92. If you need a behaviour that has landed upstream but not in a stable wheel, a development build is the documented route. Treat it as a preview channel, not a production pin.

Maintenance, versioning and the licence you are actually accepting

The repository is not archived, and the last push was on 2026-09-04, so the toolchain is being kept current. Release cadence is visible in the version numbers: 4.13.0.92 on 2026-02-03, 5.0.0.93 on 2026-07-01 and 4.14.0.94 on 2026-07-28. Note the pattern: the fourth component tracks the packaging release, while the first three track the OpenCV version. A 5.x wheel and a 4.x wheel are different OpenCV lines, so pin the full four-part version if reproducibility matters.

Upgrade cost is mostly NumPy. Because pyproject.toml pins NumPy per Python version, moving a project to a newer Python release can force a NumPy major bump along with the OpenCV wheel. Budget for that rather than discovering it in CI. The README also has a backward compatibility section, which is the place to check before assuming an API you rely on survives a major-version move.

The repository's own licence is MIT, per LICENSE.txt. That covers the packaging toolchain in this repository. It does not settle the licence of the OpenCV code compiled into the wheels, and the presence of LICENSE-3RD-PARTY.txt indicates third-party components are bundled. If you redistribute the wheels or ship them inside a product, read those files and the OpenCV licence rather than assuming MIT applies to everything in the binary. This is a description of what the repository contains, not legal advice.

The README also opens with a funding appeal for OpenCV, which is a maintenance signal in itself: the wheels are free to install, and the project asks for donations to keep the library free.

Editorial conclusion

Adopt opencv-python when you want CPU-only OpenCV without a source build: install exactly one of the four packages, and use opencv-python-headless for containers or any environment without GUI libraries. Do not adopt it if you need CUDA or other modules the default build omits, because the README points those users at a manual build from source instead. Before installing, check your pip version with pip -V and upgrade it if it is below 19.3, since older pip falls back to a source distribution that fails with ModuleNotFoundError: No module named 'skbuild'. On Windows, verify the Visual C++ redistributable is present before debugging anything else.

Frequently asked questions

Official sources

1. License: MIT
2. opencv/opencv-python on GitHub
3. Project website
4. README
5. Releases