Home › Python

ModuleNotFoundError: No module named 'cv2' (Python) — how to fix

Traceback (most recent call last):
  File "app.py", line 1, in <module>
    import cv2
ModuleNotFoundError: No module named 'cv2'

Quick fix: Install the package under its pip name with the same interpreter that runs your code: python -m pip install opencv-python (or opencv-python-headless on servers/Docker). Check with python -c "import cv2; print(cv2.__version__)".

What it means

Python searched every directory on sys.path and found no cv2 package. Almost always that's because OpenCV is not installed for this interpreter — either it was never installed, or it was installed into a different Python (system vs. venv vs. conda vs. Jupyter kernel).

The import name and the package name differ: you import cv2, but you install opencv-python. pip install cv2 fails with "No matching distribution found".

Fix 1: install the right package

python -m pip install opencv-python

Pick one of the four official wheels (install only one — they all provide cv2 and conflict with each other):

Package Use when
opencv-python Desktop, needs cv2.imshow windows
opencv-python-headless Servers, Docker, CI — no GUI libraries
opencv-contrib-python You need extra modules (cv2.xfeatures2d, cv2.aruco...)
opencv-contrib-python-headless Contrib modules on a server

If you have several installed, clean up first:

python -m pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
python -m pip install opencv-python-headless

Fix 2: you installed it into a different Python

Using bare pip can target another interpreter. Compare:

which python; python -c "import sys; print(sys.executable)"
python -m pip --version     # shows which Python this pip belongs to

Always use python -m pip install ... with the exact python that runs your script. In a virtual environment, activate it first:

source .venv/bin/activate      # Windows: .venv\Scripts\activate
python -m pip install opencv-python

In VS Code, check the interpreter shown in the status bar (Ctrl+Shift+P → "Python: Select Interpreter") matches the venv.

Fix 3: Jupyter notebook kernel

The notebook kernel may be a different Python than your terminal. Install from inside the notebook so it uses the kernel's interpreter:

%pip install opencv-python

Then restart the kernel.

Fix 4: conda environments

conda activate myenv
conda install -c conda-forge opencv

Don't mix the conda opencv package and pip opencv-python in the same environment.

Fix 5: Raspberry Pi / Debian system Python

On Debian 12+, Ubuntu 23.04+ and Raspberry Pi OS Bookworm, pip install into the system Python is blocked (see externally-managed-environment). Use the distro package:

sudo apt install python3-opencv

or create a venv and install opencv-python there.

After installing: ImportError: libGL.so.1

If the error changes to ImportError: libGL.so.1: cannot open shared object file, the module is found but GUI system libraries are missing — switch to opencv-python-headless or install libgl1. See the libGL.so.1 fix.

Last updated 2026-11-09.