How to Install OpenCV in Python

What you’ll build or solve

You’ll install OpenCV into the Python environment you actually run, then confirm Python can import it.

When this approach works best

Installing OpenCV works best when you want to:

• Read, resize, crop, or save images in a script.
• Process video frames from a file or webcam.
• Follow a computer vision tutorial that uses cv2 for basic operations.

This is a bad idea when you only need simple image I/O and resizing for a small task. In that case, a lighter library like Pillow may be enough.

Prerequisites

• Python 3 installed
• Access to a terminal (Command Prompt, PowerShell, or a macOS/Linux terminal)

Step-by-step instructions

1) Install OpenCV with pip

The pip package name is opencv-python, but you import it as cv2.

Option A: Install the main package (most common)

python-m pip install opencv-python

Option B: Install without extra GUI dependencies

If you run on a server or inside a container with no display, use the headless build.

python-m pip install opencv-python-headless

Option C: Install a specific version

python-m pip install"opencv-python==4.9.0.80"

What to look for:

If you switch between opencv-python and opencv-python-headless, uninstall the other one first to avoid conflicts.

python-m pip uninstall opencv-python opencv-python-headless

2) Confirm the install worked

Import cv2 and print its version.

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

What to look for:

ModuleNotFoundError: No module named 'cv2' usually means you installed OpenCV for a different Python than the one you are running.

3) Install in a virtual environment (recommended for projects)

After creating and activating a virtual environment, install OpenCV there:

python-m pip install opencv-python

Confirm which interpreter you are using:

python-c"import sys; print(sys.executable)"

The path should point inside your virtual environment folder (often .venv).

Examples you can copy

Example 1: Install and verify in one go

python-m pip install opencv-python
python-c"import cv2; print(cv2.__version__)"

Example 2: Install the headless build for servers

python-m pip install opencv-python-headless
python-c"import cv2; print(cv2.__version__)"

Example 3: Check which Python and pip you are using

python-c"import sys; print(sys.executable)"
python-m pip--version

Example 4: Simple import test script

importcv2

print(cv2.__version__)

Run it with:

python test.py

Example 5: Install inside an already activated virtual environment

python-m pip install opencv-python
python-c"import cv2; print(cv2.__version__)"
python-c"import sys; print(sys.executable)"

Common mistakes and how to fix them

Mistake 1: Installing the wrong package name

What you might do

python-m pip install cv2

Why it breaks

The package is named opencv-python. cv2 is the module you import.

Corrected approach

python-m pip install opencv-python
python-c"import cv2; print(cv2.__version__)"

Mistake 2: Installing in one environment, running Python in another

What you might do

• Install OpenCV in a virtual environment
• Run python outside that environment and try to import cv2

Why it breaks

Each environment has its own site-packages, so the import can fail.

Corrected approach

Confirm the interpreter path, then install again using the same interpreter:

python-c"import sys; print(sys.executable)"
python-m pip install opencv-python

Troubleshooting

If you see ModuleNotFoundError: No module named 'cv2', do this:

python-c"import sys; print(sys.executable)"
python-m pip install opencv-python

Make sure you install OpenCV with the same interpreter you run.

If you see GUI-related errors on a server, use the headless build:

python-m pip install opencv-python-headless

If you get dependency conflicts between headless and non-headless, uninstall both, then install only one:

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

If you see permission errors on macOS/Linux, either use a virtual environment or install for your user:

python-m pip install--user opencv-python

If you are on Windows and python opens the Store, use the launcher:

py-m pip install opencv-python
py-c"import cv2; print(cv2.__version__)"

Quick recap

• Install OpenCV with python -m pip install opencv-python
• Import it as cv2 and verify with python -c "import cv2; print(cv2.__version__)"
• Use opencv-python-headless for servers or environments without a display
• Install in a virtual environment for projects, then install OpenCV inside it
• If imports fail, check sys.executable to confirm which Python you are running