Fix: ModuleNotFoundError: No module named 'cv2'

Updated 2026-03-06

The Error

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

You might also see this variant inside a Jupyter notebook:

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[1], line 1
----> 1 import cv2

ModuleNotFoundError: No module named 'cv2'

The Fix

1. Install opencv-python, not cv2. The package name on PyPI doesn’t match the import name.

pip install opencv-python

Verify it worked:

import cv2
print(cv2.__version__)  # 4.10.0

2. If you need extra codecs (H.264/H.265 video, extended image formats), install the contrib build instead:

pip install opencv-contrib-python

3. If you’re using a virtual environment and the install succeeded but the import still fails, confirm you’re running Python from the right environment:

which python
# Should point to your venv, e.g.: /home/user/project/.venv/bin/python

pip show opencv-python
# Should show Location inside that same venv

If which python points to your system Python while your venv is active, deactivate and reactivate:

deactivate
source .venv/bin/activate
pip install opencv-python

4. If you’re on a headless server (no display) and see a secondary error like ImportError: libGL.so.1: cannot open shared object file, install the headless variant:

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

This drops GUI dependencies (highgui, GTK, Qt) that don’t exist on servers. It’s the correct choice for Docker containers, CI pipelines, and cloud functions.

5. If you have multiple Python versions installed, make sure pip matches your Python:

python3.12 -m pip install opencv-python

Using python3.12 -m pip guarantees the package lands in 3.12’s site-packages, not some other version’s.

Why This Happens

The disconnect is simple: the Python package is called opencv-python but you import it as cv2. There’s no cv2 package on PyPI. Running pip install cv2 either fails outright or installs an unrelated package that has nothing to do with OpenCV. This naming mismatch trips up everyone the first time.

The second most common cause is virtual environment confusion. You install opencv-python globally, but your project runs inside a venv that doesn’t have it. Or you install it in one venv, then activate a different one. Python’s import system searches sys.path in order, and if your venv’s site-packages doesn’t contain cv2, the import fails even though pip list in another terminal shows it installed.

On Linux servers, there’s an additional wrinkle. OpenCV’s default build links against libGL.so, a display library that doesn’t ship with headless server distributions. The package installs fine, but importing it fails with a shared library error that looks completely unrelated to the original ModuleNotFoundError. The opencv-python-headless package solves this by compiling without GUI support.

Finally, there are four distinct OpenCV packages on PyPI, and you should only have one installed at a time:

Installing more than one causes conflicts because they all provide the cv2 namespace. If you’ve got multiple installed, clean up:

pip uninstall opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless -y
pip install opencv-python  # or whichever one you need

Edge Cases

Conda environments. If you’re using Conda, install from the conda-forge channel instead of pip:

conda install -c conda-forge opencv

Mixing pip and conda for the same package can corrupt your environment. Pick one package manager and stick with it.

Docker builds. A common Dockerfile mistake is installing opencv-python instead of the headless variant, then wondering why the image bloats by 800MB with unnecessary X11 libraries. Use this pattern:

FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libglib2.0-0 \
    libsm6 \
    libxrender1 \
    libxext6 \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir opencv-python-headless==4.10.0.84

The apt-get dependencies are minimal runtime libraries that opencv-python-headless still needs. Without them, you’ll get a different ImportError about missing .so files.

Apple Silicon Macs. On M1/M2/M3 machines, pip install opencv-python works natively as of version 4.6+. If you’re on an older pinned version that predates ARM wheels, you’ll get a build failure. Upgrade to 4.10+ or install from conda-forge.

pyproject.toml and requirements.txt. Make sure your dependency file lists opencv-python, not cv2:

# requirements.txt
opencv-python==4.10.0.84

# pyproject.toml
[project]
dependencies = [
    "opencv-python>=4.10.0",
]

Python 3.13 compatibility. As of March 2026, opencv-python 4.10.x ships with Python 3.13 wheels. If you’re on a pre-release Python version without wheels, pip will try to build from source and fail unless you have CMake and a C++ compiler installed. Either downgrade Python to 3.12 or wait for official wheels.

See Also

• Fix: openai.RateLimitError: You exceeded your current quota