ModuleNotFoundError: No module named 'cv2' — All Fix Methods

ModuleNotFoundError: No module named 'cv2' — All Fix Methods

You run import cv2 and get:

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. This trips up nearly everyone the first time.

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). Requires a display server. Use this for desktop development.
  • opencv-python-headless — same as above but without GUI dependencies. Use this on servers, Docker containers, CI/CD, and cloud environments where there is no display.
  • opencv-contrib-python — includes everything in opencv-python plus extra modules (SIFT, SURF, text detection, tracking algorithms). Use when you need non-free or experimental algorithms.
  • opencv-contrib-python-headless — contrib package without GUI. For server deployments that need extra algorithms.

Install only one. Installing multiple causes conflicts because they all provide the same cv2.so file.

# Most common case: local development
pip install opencv-python

# Server / Docker / cloud
pip install opencv-python-headless

# Need SIFT, tracking, or other extra algorithms
pip install opencv-contrib-python

# Verify installation
python -c "import cv2; print(cv2.__version__)"

The Most Common Mistake: Installing in the Wrong Environment

You installed OpenCV, the import still fails. This almost always means you installed into a different Python environment than the one running your script.

# Check which Python your script uses
which python
# /home/user/.venv/bin/python

# Check which pip you used
which pip
# /usr/bin/pip   ← system pip, not the venv pip!

# pip install went to system Python, but script runs in venv

# Fix: always install using the pip that belongs to your environment
/home/user/.venv/bin/pip install opencv-python
# or equivalently:
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. This is the safest habit.

# Confirm the install location matches your Python
python -m pip show opencv-python
# Look at "Location:" — it should match the site-packages of your active Python

python -c "import sys; print(sys.path)"
# The Location from above should appear in this list

Conda vs pip Conflicts

If you are using conda, mixing conda and pip installs for OpenCV causes problems. Choose one method and stick with it.

# Conda install (recommended if already in a conda environment)
conda install -c conda-forge opencv

# Verify
python -c "import cv2; print(cv2.__version__)"

The conda-forge package is named opencv, not opencv-python. It includes both the main and headless variants. Do not mix conda and pip OpenCV packages in the same environment — they install to different locations and one will shadow the other unpredictably.

If you have a conflict from mixed installs:

# Remove all OpenCV pip packages first
pip uninstall opencv-python opencv-python-headless opencv-contrib-python -y

# Then reinstall cleanly from one source
conda install -c conda-forge opencv
# or
pip install opencv-python

Fixing in Jupyter Notebooks

Jupyter kernels run in their own Python environment. 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
import sys
!{sys.executable} -m pip install opencv-python-headless

Using sys.executable ensures pip installs into exactly the same Python that the kernel is using. Do not use !pip install directly — it may use the system pip instead of the kernel's pip.

After installing in a cell, restart the kernel — the module needs to be reimported in a fresh process:

# After pip install and kernel restart:
import cv2
print(cv2.__version__)  # should print e.g. "4.9.0"

Fixing in Google Colab

Colab has OpenCV pre-installed as part of the base image. If you still get the error, it is usually because a cell ran !pip uninstall opencv-python earlier in the session, or a package dependency removed it.

# In Colab: check what is installed
!pip show opencv-python opencv-python-headless 2>/dev/null || echo "Not installed"

# Reinstall headless (Colab has no display server)
!pip install opencv-python-headless -q

# Restart runtime after install, then:
import cv2
print(cv2.__version__)

In Colab, prefer opencv-python-headless — the runtime does not have a display server, so functions like cv2.imshow() will fail anyway. Use cv2_imshow from google.colab.patches for displaying images:

from google.colab.patches import cv2_imshow
import cv2

img = cv2.imread('image.jpg')
cv2_imshow(img)  # works in Colab; cv2.imshow() would crash

Checking for Conflicting Installs

If you have installed multiple OpenCV packages at different times, they will conflict. Only one can be active. Check and clean up:

pip list | grep opencv
# opencv-python             4.8.0.76
# opencv-python-headless    4.9.0.80   ← conflict!

# Remove all, reinstall only what you need
pip uninstall opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless -y
pip install opencv-python-headless

Verification Checklist

# 1. Confirm install
pip show opencv-python
# or
pip show opencv-python-headless

# 2. Confirm the right Python finds it
python -c "import cv2; print(cv2.__version__)"

# 3. Check where it is installed
python -c "import cv2; print(cv2.__file__)"
# e.g. /home/user/.venv/lib/python3.11/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)
"

For computer vision pipelines that use embeddings or similarity search alongside OpenCV, see the FAISS error guide for common issues with vector index operations.