Fix ModuleNotFoundError: No module named 'cv2' (OpenCV)
- Install the right name with the right Python:
python -m pip install opencv-python(oropencv-python-headlesson servers). There is nocv2package on PyPI:pip install cv2fails withNo matching distribution found for cv2. - Installed but still missing? Run
python -c "import sys; print(sys.executable)"and compare it withpip --version. If they point at different environments, pip installed OpenCV somewhere else. - Keep exactly one OpenCV package per environment. They all write the same
cv2/folder, so uninstalling one of two removescv2for both. Fix: uninstall all four, then install one. ImportError: libGL.so.1orlibxcb.so.1: cannot open shared object filein Docker: switch toopencv-python-headless, orapt-get install libgl1 libglib2.0-0.A module that was compiled using NumPy 1.x cannot be run in NumPy 2: your OpenCV is older than 4.10. Upgrade it (pip install -U opencv-python) rather than downgrading numpy.
You run import cv2 and get:
Traceback (most recent call last):
File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'cv2'The confusing part: OpenCV does not have a package named cv2 on PyPI. The module is called cv2 inside Python, but the installable packages have completely different names. Every error below was reproduced on the date above, not copied from forum posts.
Reproduced: Each Error and the Fix That Worked
Setup: python3 -m venv on Ubuntu 24.04 with Python 3.12.3, pip install --upgrade pip (26.2.1). A plain pip install opencv-python resolved to opencv-python 5.0.0.93 with numpy 2.5.3. Docker rows used a fresh python:3.12-slim container each time.
| What I ran | Exact error or output | Fix that worked |
|---|---|---|
import cv2 in a fresh venv | ModuleNotFoundError: No module named 'cv2' | python -m pip install opencv-python |
pip install cv2 | ERROR: Could not find a version that satisfies the requirement cv2 (from versions: none) then ERROR: No matching distribution found for cv2 | Install opencv-python (or one of its variants) |
Venv A active, ran venv B's pip install opencv-python-headless, then import cv2 | pip printed Successfully installed; import still gave No module named 'cv2' | python -m pip install opencv-python-headless (installed into A) |
python3 -m pip install opencv-python with Ubuntu's system Python | error: externally-managed-environment | Create and activate a venv first |
opencv-python + opencv-contrib-python, then uninstalled contrib | ModuleNotFoundError: No module named 'cv2' (the whole cv2/ folder was gone) | pip install --force-reinstall --no-deps opencv-python |
opencv-python + opencv-python-headless, then uninstalled headless | AttributeError: module 'cv2' has no attribute '__version__'; pip check said No broken requirements found | Uninstall all four OpenCV packages, install one |
cv2.imshow() with opencv-python-headless | cv2.error: OpenCV(5.0.0) ... error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. | Use opencv-python on a desktop, or write images with cv2.imwrite() |
pip install opencv-python (5.0.0.93) in python:3.12-slim | ImportError: libxcb.so.1: cannot open shared object file: No such file or directory | pip install opencv-python-headless (imported with no apt packages), or the apt fix below |
| Same, 4.11.0.86 or 4.9.0.80 | ImportError: libGL.so.1: cannot open shared object file: No such file or directory | Same two options |
Slim + opencv-python, apt-get install libgl1 only | ImportError: libgthread-2.0.so.0: cannot open shared object file: No such file or directory | apt-get install libgl1 libglib2.0-0 (then 5.0.0 printed) |
opencv-python-headless 4.9.0.80, then pip install "numpy>=2" (got 2.5.3) | A module that was compiled using NumPy 1.x cannot be run in NumPy 2.5.3 as it may crash. ending in ImportError: numpy.core.multiarray failed to import | pip install -U opencv-python-headless (5.0.0 with numpy 2.5.3 worked; 4.11.0.86 also worked with 2.5.3) |
pip install "numpy<2" opencv-python-headless | No error: pip picked opencv-python-headless 4.11.0.86 instead of 5.0, because 5.0.0.93 requires numpy>=2 | Nothing to fix, but pin numpy<2 only if another package needs it |
The Four OpenCV Packages: Which One to Install
There are four official OpenCV packages on PyPI. They all install the same cv2 module but differ in what they include:
- opencv-python: main package, includes GUI functions (
cv2.imshow,cv2.waitKey). Needs a display and the system X/GL libraries. Use this for desktop development. - opencv-python-headless: same as above but without GUI dependencies. Use this anywhere without a display, such as Docker or CI. In
python:3.12-slimit imported with no extra apt packages. - opencv-contrib-python: everything in opencv-python plus the contrib modules, such as
cv2.ximgproc,cv2.xfeatures2dandcv2.legacy. In my test,cv2.TrackerCSRT_createexisted only in contrib. SIFT is not a contrib reason any more:cv2.SIFT_createis in plain opencv-python. SURF is not usable from the PyPI contrib wheel either:cv2.xfeatures2d.SURF_create()raisedThis algorithm is patented and is excluded in this configuration. - opencv-contrib-python-headless: contrib package without GUI. For server deployments that need the extra modules.
Install only one. They all unpack into the same site-packages/cv2/ directory. Adding a second one installed without an error in my test, and pip check later reported nothing. The breakage shows up later, when you uninstall one of them (see the table: No module named 'cv2' or a half-deleted cv2 with no __version__).
# Most common case: local development
python -m pip install opencv-python
# Server / Docker / cloud
python -m pip install opencv-python-headless
# Need contrib modules (ximgproc, CSRT tracker, ...)
python -m pip install opencv-contrib-python
# Verify installation
python -c "import cv2; print(cv2.__version__)"
# 5.0.0
Installed, but the Import Still Fails: Wrong Environment
If you installed OpenCV and the import still fails, the usual cause is that you installed into a different Python environment than the one running your script. I reproduced it by activating one venv and calling another venv's pip: pip reported Successfully installed numpy-2.5.3 opencv-python-headless-5.0.0.93, and import cv2 still failed.
# Which Python runs your code?
python -c "import sys; print(sys.executable)"
# /tmp/cv2test/v4/bin/python
# Which environment does this pip install into?
pip --version
# pip 26.2.1 from /tmp/cv2test/v3/lib/python3.12/site-packages/pip (python 3.12)
# ^^ different venv: that is the bug
# Fix: install with the interpreter itself
python -m pip install opencv-python
Using python -m pip instead of bare pip guarantees you install into the same Python that will run your code.
# Confirm the install location matches your Python
python -m pip show opencv-python
# Look at "Location:"; it should be the site-packages of your active Python
python -c "import cv2; print(cv2.__file__)"
On Ubuntu 24.04 and other recent distros, installing into the system Python is blocked outright with error: externally-managed-environment. That is not an OpenCV problem: create a venv (python3 -m venv .venv && . .venv/bin/activate) and install there.
ImportError: libGL.so.1 or libxcb.so.1 in Docker
Once cv2 is found, a slim container often fails one step later, because opencv-python links against X11 and OpenGL libraries the image does not ship. Which library is missing first depends on the wheel: in python:3.12-slim, opencv-python 5.0.0.93 failed on libxcb.so.1, while 4.11.0.86 and 4.9.0.80 failed on libGL.so.1. Installing only libgl1 moved the error to libgthread-2.0.so.0.
Two fixes, both verified in a fresh container:
# Option 1 (preferred on servers): no GUI, no extra system packages
RUN pip install opencv-python-headless
# Option 2: keep opencv-python, add the system libraries it needs
RUN apt-get update \
&& apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
&& rm -rf /var/lib/apt/lists/*
RUN pip install opencv-python
If a dependency pulls in opencv-python for you, the uninstall-everything step below still applies before you add the headless package, or both will share the same cv2/ folder.
NumPy 2 and Older OpenCV Wheels
OpenCV wheels before 4.10 were built against NumPy 1.x. With opencv-python-headless 4.9.0.80 and numpy 2.5.3, import cv2 printed:
A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.5.3 as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.
If you are a user of the module, the easiest solution will be to
downgrade to 'numpy<2' or try to upgrade the affected module.
...
AttributeError: _ARRAY_API not found
...
ImportError: numpy.core.multiarray failed to importUpgrading OpenCV fixed it without touching numpy: 4.11.0.86 and 5.0.0.93 both imported with numpy 2.5.3. Going the other way, opencv 5.0.0.93 declares numpy>=2, so pip install "numpy<2" opencv-python-headless quietly resolved to 4.11.0.86. See the numpy binary incompatibility guide for the same pattern in other packages.
Conda vs pip Conflicts
Not reproduced here: this test machine used venvs only. If you are using conda, the conda-forge package is named opencv, not opencv-python. Pick one installer for OpenCV in a given environment; a conda opencv and a pip opencv-python both provide cv2, which is the same one-folder conflict as above.
# Conda install (if you are already in a conda environment)
conda install -c conda-forge opencv
# Verify
python -c "import cv2; print(cv2.__version__)"
If you have a conflict from mixed installs:
# Remove all OpenCV pip packages first
python -m pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
# Then reinstall cleanly from one source
conda install -c conda-forge opencv
# or
python -m pip install opencv-python
Fixing in Jupyter Notebooks
Not reproduced here; the cause is the same wrong-interpreter problem shown above. Jupyter kernels can run a different Python from your terminal. Even if cv2 is installed in your system Python or base conda environment, the kernel may use a different one.
# Run this in a Jupyter cell to install into the kernel's Python
%pip install opencv-python-headless
# or, equivalently:
import sys
!{sys.executable} -m pip install opencv-python-headless
Both forms install into the Python the kernel is using. A bare !pip install may use whichever pip is first on the shell's PATH instead. If import cv2 had already failed in that kernel, restart it before importing again.
Fixing in Google Colab
Not reproduced here. Colab ships OpenCV in its base image, so this error there usually means an earlier cell uninstalled or replaced it. Check with !pip list | grep -i opencv, reinstall one package, and restart the runtime. Colab has no display for cv2.imshow(); use cv2_imshow from google.colab.patches instead:
from google.colab.patches import cv2_imshow
import cv2
img = cv2.imread('image.jpg')
cv2_imshow(img)
Checking for Conflicting Installs
This is what two OpenCV packages in one venv looked like in my test. pip check did not flag it.
python -m pip list | grep opencv
# opencv-python 5.0.0.93
# opencv-python-headless 5.0.0.93 <- two packages, one cv2 folder
# Remove all, reinstall only what you need
python -m pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
python -m pip install opencv-python-headless
python -c "import cv2; print(cv2.__version__)"
# 5.0.0
pip prints WARNING: Skipping ... as it is not installed for the ones you did not have, which is harmless.
Verification Checklist
# 1. Confirm exactly one OpenCV package is installed
python -m pip list | grep -i opencv
# 2. Confirm the right Python finds it
python -c "import cv2; print(cv2.__version__)"
# 5.0.0
# 3. Check where it is installed
python -c "import cv2; print(cv2.__file__)"
# e.g. /tmp/cv2test/v1/lib/python3.12/site-packages/cv2/__init__.py
# 4. Run a basic operation to confirm it is functional
python -c "
import cv2
import numpy as np
img = np.zeros((100, 100, 3), dtype=np.uint8)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print('cv2 functional, output shape:', gray.shape)
"
# cv2 functional, output shape: (100, 100)