opencv-python is a wheel factory, and the cv2 namespace is the constraint that shapes it

Four packages install into one cv2 namespace, and headless is decided by who owns the window

The four published packages are not layers of one another. Option 1 is the main modules package, Option 2 adds contrib and extra modules, Option 3 is the headless main modules package, and Option 4 is the headless full package. The instruction is explicit: select only one of them, and do not install multiple in the same environment. The reason is structural. There is no plugin architecture, and all four write to the same cv2 namespace, so a second install overwrites files from the first rather than adding to it. Recovery is uninstall everything with pip uninstall, then install one. The headless half of that matrix is a GUI decision, not a compute one: the same modules compiled without Qt or other GUI components, which removes the dependency chain to X11 libraries and produces smaller Docker images. Use them whenever you never call cv2.imshow and friends, or when something other than OpenCV, such as PyQt, creates your window.

The build backend is a directory inside the repository, not a name on a package index

pyproject.toml points build-backend at backend and sets backend-path to _build_backend, so the backend source ships in this tree rather than being resolved from an index. The comment above it says the reason: managing the CMake check and the installation step. The requirements list shows how heavy that is. scikit-build>=0.14.0 is the CMake driver, and packaging and pip come along with it. setuptools is pinned hard on both sides of Python 3.12, at 59.2.0 below it and under 70.0.0 at or above it, which means the interpreter version you build on changes the setuptools you get.

numpy is pinned four different ways in the build requirements and two in install_requires

The build-system block pins numpy per interpreter: below 2.0 for Python under 3.9, exactly 2.0.2 from 3.9 up to 3.13, exactly 2.1.3 on 3.13, and exactly 2.3.2 on 3.14. install_requires in setup.py is much looser, asking for numpy<2.0 on Python under 3.9 and numpy>=2 from 3.9 upward. Read those two blocks separately. The tight pins govern the machine that compiles OpenCV, the loose ones govern the environment that imports cv2, and a wheel built against 2.1.3 does not advertise that as a runtime constraint. setup.py also names 1.13.3 as minimum_supported_numpy, a third number that appears in neither requirement set as written.

Build flavour comes from environment variables read through one helper

setup.py reads CI_BUILD from the environment and treats the value 1 as the CI path, defaulting to the string False. Four build switches all go through a function called get_build_env_var_by_name: contrib, headless, java, and rolling. contrib decides whether the contrib modules join the build, headless decides whether the GUI components are compiled out, and java is turned into the literal string ON or OFF that CMake consumes. Those four are the switches read through that helper.

An old pip falls back to a source build that also fails, then reports skbuild is missing

Since opencv-python 4.3.0 the manylinux1 wheels were replaced by manylinux2014 wheels. A pip older than 19.3 does not know that tag, so it reaches for the source distribution introduced in 4.3.0.38 and tries to compile OpenCV locally. That attempt fails for a second reason: the same pip cannot read build dependencies out of pyproject.toml. The error the user sees is therefore ModuleNotFoundError: No module named 'skbuild', which points at scikit-build while the real fault is the pip version. The fix is one command, and the minimum version is checked separately with pip -V. Older Linux distributions shipping pip by default are called out as the usual source of this.

The Windows import failure is a missing runtime, not a broken wheel

ImportError: DLL load failed: The specified module could not be found. is answered with a chain of environment fixes rather than a reinstall. Install the Visual C++ redistributable 2015 first. On Windows versions older than 10 without the latest updates, the Universal C Runtime may be needed as well. N and KN editions do not ship the Media Feature Pack, which OpenCV requires. On Windows Server 2012 and later the media DLLs are missing too, and the recommended feature is Media Foundation from Server Manager, explicitly in preference to the Windows Server Essentials Media Pack, because that pack requires the Windows Server Essentials Experience role and reshapes Active Directory integration. Old Anaconda versions carry a separate bug for this same error.

Release tags count builds, and a higher tag can hold an older OpenCV version

The tag sequence and the version inside it move independently. Tag 92 is 4.13.0.92, published 2026-02-03. Tag 93 is 5.0.0.93, published 2026-07-01. Tag 94 is 4.14.0.94, published 2026-07-28, so the newest build by number carries 4.x while the build before it carried 5.0.0. Choosing by tag order instead of by the OpenCV version can move you to an older library. The default branch is 4.x, and the last commit landed on 2026-09-04, after all three releases. The licence is MIT, in LICENSE.txt at the top of the tree, next to a separate LICENSE-3RD-PARTY.txt for the bundled third-party code.

What is in the tree is build tooling, submodules, and CI config, not OpenCV itself

The repository answers the question of whether you also need to install OpenCV separately: no, the wheels are special wheel binary packages that already contain statically built OpenCV binaries. The source of that library arrives as git submodules named opencv, opencv_contrib, and opencv_extra, wired through .gitmodules, and the tree also carries a multibuild directory, scripts/, docker/, patches/, a patch_auditwheel_whitelist.py, find_version.py, travis_config.sh, travis_multibuild_customize.sh and travis_osx_brew_cache.sh. The FAQ states the boundary plainly: this repository contains only the OpenCV-Python package build scripts, so a function returning a wrong result or crashing the interpreter is an upstream question, not one that can be fixed here.

Your first import reaches for data files that ship inside the wheel

Install one package, then import it. Four install commands exist, one per package, and the README tells you to pick exactly one of them rather than layering them.

pip install --upgrade pip
pip install opencv-python

Importing is one line, and every package carries the Haar cascade files with it. The shortcut attribute points at the data directory, so a classifier path is assembled by concatenating that directory with a file name rather than by hardcoding a path. That matters on Windows and in containers, where an absolute path to a checkout would be wrong.

import cv2

cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")

If that import raises something other than success, the next thing to check is a leftover manual install: a cv2.so or cv2.pyd sitting in site-packages from a build that did not go through pip will shadow the wheel. The rest of the first run is a pointer outward: read the OpenCV documentation, and before opening an issue, read the FAQ and the issues that are already open.

Editorial conclusion

Take the wheels when your target is a CPU and your platform is one the build covers, and choose between the main, contrib, and headless variants once, because installing two of them puts conflicting files in the same cv2 directory. Compile the bindings yourself when you need CUDA or another module the wheels omit. Before you commit to a version, check what your numpy pin requires, since the build requirements and the runtime requirements disagree, and read the Windows import failures below early if you deploy on that platform.

Frequently asked questions

Official sources

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