Choose your package
opencv-python vs opencv-contrib-python vs opencv-python-headless
| Package | Includes | Use when |
|---|---|---|
opencv-python | Main modules + GUI | Most users — start here |
opencv-contrib-python | Main + extra community modules | Need face recognition, SIFT, text detection |
opencv-python-headless | Main modules, no GUI | Servers, Docker, no display |
opencv-contrib-python-headless | All modules, no GUI | Server + contrib features |
Never install more than one of these at the same time. They conflict. If you see import errors after switching packages, run
pip uninstall opencv-python opencv-contrib-python opencv-python-headless then reinstall the one you need.pip install
Install OpenCV with pip
# Standard install:
C:\> pip install opencv-python
Successfully installed opencv-python-4.12.0.86
# With contrib extra modules:
C:\> pip install opencv-contrib-python
# Specific version:
C:\> pip install opencv-python==4.10.0.84
# Verify:
C:\> python -c "import cv2; print(cv2.__version__)"
4.12.0
Virtual environment (recommended)
Install OpenCV in a virtual environment
# Create venv:
C:\> python -m venv cv_env
# Activate:
C:\> cv_env\Scripts\activate
(cv_env) C:\>
# Install OpenCV:
(cv_env) C:\> pip install opencv-python
# Deactivate when done:
(cv_env) C:\> deactivate
Anaconda / conda
Install OpenCV with conda
# Install from conda-forge:
(base) C:\> conda install -c conda-forge opencv
# Or in a new environment:
(base) C:\> conda create -n cv_env python=3.11 opencv -c conda-forge
(base) C:\> conda activate cv_env
(cv_env) C:\>
See the full Conda / Anaconda guide for more details.
Quick test
Test your OpenCV Python installation
import cv2
import numpy as np
# Check version:
print(cv2.__version__)
# Create a test image and show it:
img = np.zeros((300, 400, 3), dtype=np.uint8)
cv2.putText(img, "OpenCV works!", (50,150), cv2.FONT_HERSHEY_SIMPLEX, 1, (0,255,0), 2)
cv2.imshow("Test", img)
cv2.waitKey(0)
cv2.destroyAllWindows()
FAQ
Python install questions
DLL load failed: WinError 126 after pip install
Install Visual C++ Redistributable from microsoft.com, restart, then
pip install opencv-python --force-reinstall. Full steps at opencv_iconv.dll fix guide.Which Python version is compatible with OpenCV 4.12?
OpenCV 4.12 pip wheels support Python 3.7 through 3.13 on Windows 64-bit. Python 3.10 or 3.11 is recommended for best compatibility with other data science libraries.
cv2.imshow() crashes or shows no window
Make sure you are using
opencv-python (not headless) and that your script calls cv2.waitKey(0) after imshow(). Without waitKey, the window closes immediately. In headless/server environments use cv2.imwrite() instead.pip install says "already satisfied" but import cv2 fails
You likely have multiple Python installations. Check which pip and python are being used:
where python and where pip. Make sure both point to the same installation. Or use python -m pip install opencv-python to ensure pip installs to the active Python.