Fix ModuleNotFoundError: No module named 'cv2' (OpenCV)

You install OpenCV, import it, and Python still says:

ModuleNotFoundError: No module named 'cv2'

Two things make OpenCV trickier than a normal "just pip install it." First, the import name (cv2) doesn't match the package name (opencv-python) — and there are four packages to choose from, not one. Second, on a server you often fix the cv2 error only to hit a second one, libGL.so.1: cannot open shared object file, which almost no one connects to the first.

This guide picks the right package for your environment, installs it into the right interpreter, and preempts the libGL follow-on before it bites you in Docker.

Quick Answer

No module named 'cv2' means OpenCV isn't installed in the Python you're running. You import cv2, but the pip package is opencv-python. On a desktop: pip install opencv-python. On a server/Docker/CI: pip install opencv-python-headless. Install exactly one. If import cv2 then fails with libGL.so.1, use the headless build or apt-get install -y libgl1 libglib2.0-0.

TL;DR

• Import cv2, install opencv-python — names differ.
• Four variants — pick one; never mix them.
• Servers/Docker/CI → opencv-python-headless (no GUI deps).
• opencv-contrib-python only if you need contrib (SIFT, etc.).
• libGL.so.1 follow-on → headless, or apt-get install libgl1 libglib2.0-0.
• Installed but not found? Wrong interpreter → python -m pip.

Pick the Right Package

There isn't one OpenCV package — there are four, and they all provide the same cv2 import. Choose by two questions: do you open GUI windows, and do you need the contrib modules?

# Desktop
pip install opencv-python
 
# Server / Docker / CI (recommended for backends)
pip install opencv-python-headless

pip uninstall -y opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless
pip install opencv-python-headless   # then install the one you want

There's also no package literally named cv2 — pip install cv2 won't work. The package is opencv-python (or a variant above).

The libGL Follow-On (Docker's Favorite)

Here's the sequence that catches everyone deploying to a container or server. You fix No module named 'cv2' by installing opencv-python, then import cv2 throws:

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

This isn't a Python problem — the GUI build of OpenCV links against system OpenGL libraries that a headless server doesn't have. Two fixes:

# ✅ Fix A — recommended for servers/Docker: use the headless build
pip uninstall -y opencv-python
pip install opencv-python-headless
 
# ✅ Fix B — if you truly need the full (GUI) build: install the system libs
apt-get update && apt-get install -y libgl1 libglib2.0-0

• Fix A removes the need for system GL entirely — best for backends and CI.
• Fix B keeps GUI features; libglib2.0-0 also covers a common companion error (libgthread-2.0.so.0).

RUN pip install opencv-python-headless

RUN apt-get update && apt-get install -y libgl1 libglib2.0-0 && rm -rf /var/lib/apt/lists/*
RUN pip install opencv-python

Still "No module named cv2"? Check the Interpreter

If the package installed but the import still fails, you installed it into a different Python than the one running — the general cause of every ModuleNotFoundError. The same triage as the dotenv guide applies:

pip show opencv-python                       # installed? where?
python -c "import sys; print(sys.executable)"  # which Python runs my code?
 
# install into THIS interpreter to remove ambiguity
python -m pip install opencv-python-headless

• Virtual env: activate it first, then install inside it.
• Jupyter/Colab: %pip install opencv-python-headless, then restart the kernel.
• conda: conda install -c conda-forge opencv (installs the cv2 module).

Verify

import cv2
print(cv2.__version__)     # e.g. 4.x — installed in this interpreter
 
# quick end-to-end check (no GUI needed)
import numpy as np
img = np.zeros((10, 10, 3), dtype=np.uint8)
print(cv2.cvtColor(img, cv2.COLOR_BGR2GRAY).shape)   # (10, 10)

Prevention

• Import cv2, install opencv-python (or a variant) — never cv2.
• Use opencv-python-headless for servers, Docker, and CI by default.
• Install exactly one opencv-* package.
• Pin your chosen variant in requirements.txt.
• In Docker, prefer headless; otherwise install libgl1 libglib2.0-0.
• Use python -m pip and check sys.executable when an install "doesn't take".

Troubleshooting Matrix

Related Guides

• Fix ModuleNotFoundError: No module named 'dotenv'
• Fix ImportError: cannot import name 'Mapping' from 'collections'
• Fix torch.cuda.is_available() returns False
• Fix TypeError: Object of type datetime is not JSON serializable
• Dockerizing Python computer-vision apps

External References

• opencv-python on PyPI (package variants)
• OpenCV-Python — installation docs
• opencv-python FAQ (headless, libGL)
• pip — Installing packages

FAQs

Why is the import cv2 and not opencv? Historical: OpenCV's Python bindings have always exposed the module as cv2 (the 2 is from the C++ API generation, not the version). The pip distribution is named opencv-python. Import name and package name simply differ, like opencv-python → cv2 and python-dotenv → dotenv.

Is headless missing any image processing? No. Headless has the same image/video processing functions — it only omits the GUI/window functions (imshow, waitKey, namedWindow). For servers and pipelines you never use those anyway, so headless is a pure win.

Do I need NumPy too? opencv-python depends on NumPy and installs it automatically. If you see a NumPy error instead, it's usually a version mismatch — upgrade both: pip install -U numpy opencv-python-headless.

Which variant for a Flask/FastAPI backend? opencv-python-headless. Backends don't open windows, and headless avoids the libGL dependency entirely — fewer system packages, smaller image, no surprise runtime error.

How do I switch from the GUI build to headless? Uninstall the GUI build first, then install headless — don't layer them: pip uninstall -y opencv-python && pip install opencv-python-headless. Having both is what causes conflicts.