TopolearnMissing codecs, GUI errors on servers and absent modules all trace back to which OpenCV build is installed.
OpenCV ships on PyPI as four mutually exclusive wheels that all provide the same cv2 module:
opencv-python: main modules plus GUI (imshow) supportopencv-python-headless: no GUI dependencies; for servers, Docker and CIopencv-contrib-pythonandopencv-contrib-python-headless: add the extra contrib modules (cv2.ximgproc,cv2.xfeatures2d,cv2.face, tracking extras and more)
Install exactly one. Having two installed (often pulled in by different dependencies) makes them overwrite each other's files and leads to errors such as "module cv2 has no attribute". Fix by uninstalling all variants and reinstalling one.
print(cv2.getBuildInformation()) shows how your copy was built: version, enabled modules, video I/O backends (FFmpeg, GStreamer, V4L, Media Foundation), parallel framework, SIMD dispatch, OpenCL and whether CUDA is present. It answers most "why doesn't this codec/camera/feature work" questions.
The pip wheels don't include CUDA, non-free algorithms or GStreamer on every platform. When you need those, build from source with CMake (enabling WITH_CUDA, OPENCV_EXTRA_MODULES_PATH for contrib, and so on) or use a distribution package that has them.
Major versions matter too. OpenCV 5 reorganises some C++ modules (for example splitting calibration and 3-D code) and modernises the dnn engine, but the Python cv2.* API stays largely compatible; check cv2.__version__ when following older tutorials.
Example
import cv2
print(cv2.__version__) # e.g. 4.12.0 or 5.0.0
info = cv2.getBuildInformation()
for line in info.splitlines():
if any(k in line for k in ("FFMPEG", "GStreamer", "Parallel framework", "OpenCL:")):
print(line.strip())
# FFMPEG: YES ... / Parallel framework: pthreads / OpenCL: YES ...
print(hasattr(cv2, "SIFT_create")) # True (main module since 4.4)
print(hasattr(cv2, "ximgproc")) # True only with a contrib wheel
print(cv2.cuda.getCudaEnabledDeviceCount() if hasattr(cv2, "cuda") else 0)
# 0 with pip wheels: no CUDA support compiled inRemember
- Four wheels (main/contrib x GUI/headless); install exactly one
- cv2.getBuildInformation() reveals backends, codecs and acceleration
- CUDA and some extras need a source build
- Check cv2.__version__ when following older tutorials
Watch out for
- Installing both opencv-python and opencv-python-headless, which overwrite each other's cv2 files.