iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
The command pip install cv2 fails because cv2 is the name you use in Python, not the name of the standard PyPI package. Install the distribution named opencv-python, then import it as cv2.
python -m pip install opencv-pythonThis guide covers the correct package choices, virtual-environment installation, verification, common errors, and a small image-processing example.
What is the correct package name?
OpenCV uses two names in a Python project:
| Purpose | Name |
|---|---|
| Package installed from PyPI | opencv-python |
| Module imported by Python | cv2 |
Therefore, this is the normal pattern:
python -m pip install opencv-pythonimport cv2There is no standard PyPI package named cv2 for this installation. If you run pip install cv2, pip normally reports that it cannot find a matching distribution.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteInstall OpenCV with pip
Linux and macOS
Upgrade pip first, then install the package:
python -m pip install --upgrade pip
python -m pip install opencv-pythonWindows
Use the Python launcher so pip is tied to the interpreter selected by Windows:
py -m pip install --upgrade pip
py -m pip install opencv-pythonThe OpenCV-Python project requires pip 19.3 or newer for correct handling of its manylinux2014 wheels. Updating pip avoids a common situation in which pip ignores a compatible wheel and tries to build OpenCV from source.
Use a virtual environment
A virtual environment prevents OpenCV from interfering with packages installed for other projects. From your project directory, run:
Linux or macOS
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install opencv-pythonWindows PowerShell
py -m venv .venv
.venvScriptsActivate.ps1
python -m pip install --upgrade pip
python -m pip install opencv-pythonWindows Command Prompt
py -m venv .venv
.venvScriptsactivate.bat
python -m pip install --upgrade pip
python -m pip install opencv-pythonYou do not have to activate the environment. You can call its interpreter directly:
.venv/bin/python -m pip install opencv-python
.venv/bin/python -c "import cv2; print(cv2.__version__)"On Windows, use .venvScriptspython.exe instead of .venv/bin/python. If PowerShell blocks Activate.ps1, Python’s documentation gives this per-user setting:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserYou can also create the environment and update its core pip dependency in one command on supported Python versions:
python -m venv .venv --upgrade-depsChoose the right OpenCV package
Install exactly one OpenCV package variant in an environment. All four provide the same cv2 namespace, so installing combinations can overwrite shared files.
| Package | Use it when |
|---|---|
opencv-python |
You need the standard modules and desktop GUI functions such as cv2.imshow(). |
opencv-contrib-python |
You need OpenCV’s extra or contrib modules, including the standard desktop functionality. |
opencv-python-headless |
Your application runs on a server, in Docker, or in the cloud and does not open OpenCV GUI windows. |
opencv-contrib-python-headless |
You need contrib modules in a non-GUI environment. |
Install alternatives with these commands:
python -m pip install opencv-contrib-python
python -m pip install opencv-python-headless
python -m pip install opencv-contrib-python-headlessThe headless packages are not simply smaller desktop packages. They are built without GUI dependencies such as Qt. Do not install one if your program calls cv2.imshow(), cv2.waitKey(), or other HighGUI functions.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →The standard pip wheels include the OpenCV binaries. You normally do not need a separate system-wide installation through apt, Homebrew, or the Windows installer. A second manual installation can create duplicate cv2.so or cv2.pyd files and make imports unpredictable.
Check that the installation works
Run this command with the same interpreter that will run your program:
python -c "import cv2; print(cv2.__version__)"On Windows:
py -c "import cv2; print(cv2.__version__)"As of August 7, 2026, the latest release listed on PyPI is opencv-python 5.0.0.93, released July 2, 2026. The current release publishes wheels for CPython 3.7 through 3.14. PyPI metadata still declares Python 3.6 or newer, but Python 3.6 is not among the current prebuilt-wheel targets and may require a source build or fail to resolve a compatible wheel.
To see which file Python is importing, use:
python -c "import cv2; print(cv2.__file__); print(cv2.__version__)"Basic OpenCV image example
Create a file named image_test.py in a directory containing input.jpg:
import cv2
image = cv2.imread("input.jpg")
if image is None:
raise FileNotFoundError("Could not read input.jpg")
cv2.imshow("Image", image)
cv2.waitKey(0)
cv2.destroyAllWindows()
if not cv2.imwrite("output.jpg", image):
raise OSError("Could not write output.jpg")Run it with:
python image_test.pycv2.imread() returns an image array when it can read the file. If the path is wrong, the file is missing, or the format cannot be decoded, it returns None. Check that result before passing the image to other OpenCV functions.
cv2.waitKey(0) waits indefinitely for a key press, keeping the window available. cv2.destroyAllWindows() then closes OpenCV-created windows. This example requires the non-headless package and a working desktop display.
Convert between BGR, RGB, and grayscale
OpenCV loads color images in BGR channel order. Many other Python imaging and plotting libraries expect RGB. Passing an OpenCV image directly to such a library can swap the red and blue channels.
import cv2
image = cv2.imread("input.jpg")
if image is None:
raise FileNotFoundError("Could not read input.jpg")
rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
gray_image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
cv2.imwrite("gray.jpg", gray_image)Use COLOR_BGR2RGB when handing an image to an RGB-based library, and COLOR_BGR2GRAY when you need a single-channel grayscale image.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesFix common installation errors
ERROR: Could not find a version that satisfies the requirement cv2
Replace the package name:
python -m pip install opencv-pythoncv2 is the import namespace, not the normal distribution name.
ModuleNotFoundError: No module named 'cv2'
The most common cause is installing into one Python environment and running the script with another. Use the same interpreter for both operations:
python -m pip install opencv-python
python -c "import cv2; print(cv2.__version__)"If you use a virtual environment, activate it before both commands, or call its full interpreter path. Check the selected executables with:
python -c "import sys; print(sys.executable)"
python -m pip --versionModuleNotFoundError: No module named 'skbuild'
This commonly occurs with an old pip that does not recognize a compatible manylinux2014 wheel and falls back to a source distribution. Upgrade pip and retry:
Recommended Free Tools
python -m pip install --upgrade pip
python -m pip install --force-reinstall opencv-pythonCould not build wheels for opencv-python
Pip attempted a source build instead of selecting a prebuilt wheel. Likely causes include an outdated pip, an unsupported Python version, an unsupported operating system or CPU architecture, or a platform for which the project does not publish a wheel.
First upgrade pip and confirm your interpreter version:
python -m pip install --upgrade pip
python --version
python -m pip debug --verboseA source build requires a C/C++ toolchain and can take a long time. On low-powered systems such as a Raspberry Pi, a full OpenCV build may take several hours.
Windows: ImportError: DLL load failed
Possible causes include a missing Visual C++ Redistributable 2015, an older Windows system without the Universal C Runtime, a Windows N or KN installation without the Media Feature Pack, or Windows Server without Media Foundation. Old Anaconda installations and conflicting cv2.pyd files can cause the same message.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Inspect the installed extension under a location similar to:
C:UsersusernameAppDataLocalProgramsPythonPythonXXLibsite-packagescv2If you previously copied OpenCV files manually, remove obsolete cv2.pyd files before reinstalling the pip package.
OpenCV crashes after installing several variants
Remove every OpenCV-Python variant, then install only the one you need:
python -m pip uninstall opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless
python -m pip install opencv-pythonUse opencv-contrib-python instead if you need the extra modules. Do not install it alongside opencv-python.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
cv2.imshow() reports “The function is not implemented”
A headless package is probably installed. Replace it with a desktop package:
python -m pip uninstall opencv-python-headless opencv-contrib-python-headless
python -m pip install opencv-pythonIf the program runs on a server or in Docker, keep the headless package and save images to disk or return them through your application instead of opening a GUI window.
cv2.imread() returns None
Print the process’s working directory and use an explicit path while diagnosing:
from pathlib import Path
import cv2
path = Path("input.jpg").resolve()
print("Reading:", path)
print("Exists:", path.exists())
image = cv2.imread(str(path))
if image is None:
raise FileNotFoundError(f"OpenCV could not read {path}")This distinguishes a bad relative path from a decoding or file-permission problem.
Compatibility notes
- The standard
opencv-pythonandopencv-contrib-pythonwheels are CPU-only. CUDA-enabled Python bindings require a custom OpenCV build rather than the normal pip wheels. - Linux wheels changed from
manylinux1tomanylinux2014starting with package version 4.3.0. Older Linux distributions may not be compatible. - OpenCV-Python builds dropped support for macOS versions older than 10.13 starting with version 4.2.0 and OpenCV 3.4.9 builds. Later releases further deprecated macOS 10.x build environments.
- For custom wheel work, current project guidance uses
pip wheel . --verbose; the olderpython setup.py bdist_wheelcommand is not the normal approach for projects usingpyproject.toml.
FAQ
Can I install OpenCV with pip install cv2?
No. Install opencv-python with python -m pip install opencv-python, then use import cv2 in Python.
Do I need to install OpenCV separately with apt, Homebrew, or the Windows installer?
Usually not. The official pip wheels include the OpenCV binaries needed for normal Python use. A separate system installation can create duplicate files and import conflicts.
Should I install opencv-python and opencv-contrib-python together?
No. Choose opencv-contrib-python by itself when you need the extra modules. The packages share the cv2 namespace and should not be installed together.
Which OpenCV package should I use in Docker?
Use opencv-python-headless for a normal non-GUI workload, or opencv-contrib-python-headless if you need contrib modules. Do not use these packages with cv2.imshow().
Free tools Windows power users keep installed
One-click scans. No signup required.
Why are my OpenCV colors red and blue swapped?
cv2.imread() returns BGR images, while many libraries expect RGB. Convert explicitly with cv2.cvtColor(image, cv2.COLOR_BGR2RGB).
Does pip install opencv-python provide CUDA support?
No. The standard OpenCV-Python wheels are CPU-only. CUDA support requires building OpenCV and its Python bindings with a suitable custom configuration.
The Bottom Line
Use python -m pip install opencv-python, not pip install cv2. Keep the installation in the same virtual environment and interpreter that runs your code, install only one OpenCV package variant, and verify it with python -c "import cv2; print(cv2.__version__)". Choose a headless package only when your application does not need OpenCV GUI functions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
