Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 54 ยท Getting Started

Installing OpenCV

Install OpenCV with pip in a virtual environment. Choose between opencv-python, headless and contrib builds, verify cv2.__version__ and fix common errors.

Installing OpenCV for Python is one command, but there are four different packages on PyPI and picking the wrong one is the most common beginner snag. This lesson explains the differences, shows the safe way to install into a virtual environment, and gives you a short script to check that everything works.

The commands below run on your computer, not on this page, so they are shown as read-only blocks. The TryIts in this lesson are small Python helpers that make the decisions clearer.

The four packages

All four provide the same import cv2. They differ in what is compiled in:

Package Contains Use it for
opencv-python Main modules plus GUI support (imshow) Learning and desktop scripts
opencv-contrib-python Main modules, GUI and extra contrib modules When you need extras such as additional trackers
opencv-python-headless Main modules, no GUI Servers, containers, CI
opencv-contrib-python-headless Contrib, no GUI Servers that need contrib

Pick exactly one

Desktop opencv-python shows windows.
Server Headless has no windows and is smaller.
Extras Contrib adds experimental modules.

Never install two of these into one environment.

1 / 2

Install only one of these packages per environment. They all write the same cv2 files, so installing two (for example opencv-python and opencv-python-headless) makes them overwrite each other and causes confusing import errors. If that happens, uninstall all of them and install one again.

Step 1: make a virtual environment

A virtual environment keeps this project's packages separate from the rest of your system. On macOS or Linux:

Terminal
python3 -m venv .venv
source .venv/bin/activate

On Windows PowerShell:

POWERSHELL
python -m venv .venv
.venv\Scripts\Activate.ps1

Your prompt now shows (.venv). Anything you install goes into that folder only.

Step 2: install with pip

For this course, opencv-python plus NumPy is what you want:

Terminal
python -m pip install --upgrade pip
python -m pip install opencv-python

NumPy arrives automatically as a dependency. Using python -m pip guarantees that pip belongs to the Python you just activated. On a server or in Docker, swap in the headless build:

Terminal
python -m pip install opencv-python-headless

If you use conda, the community channel carries OpenCV too:

Terminal
conda create -n vision python=3.12
conda activate vision
conda install -c conda-forge opencv

To record the dependency for a project, list it in requirements.txt, pinned to the version you tested:

TEXT
opencv-python==4.*
numpy

Platform notes: Windows, Linux and Anaconda

Windows. Install Python from python.org and tick Add python.exe to PATH on the first screen of the installer. The py launcher is installed too, so py -m venv .venv, .venv\Scripts\activate and py -m pip install opencv-python work in PowerShell or Command Prompt. If python opens the Microsoft Store, disable the "App execution aliases" for python in Windows settings. After installing, restart the terminal so the new PATH is used.

Linux. Install Python and the venv and pip packages with your package manager: sudo apt install python3 python3-venv python3-pip (Ubuntu, Debian), sudo dnf install python3 python3-pip (Fedora), sudo pacman -S python python-pip (Arch) or sudo zypper install python3 python3-pip (openSUSE). Then use a virtual environment and pip install opencv-python as above. Distribution packages such as python3-opencv also exist, but they are often older than the pip release and cannot be mixed with a pip-installed copy in the same environment. On a server without a desktop, install opencv-python-headless; if import cv2 complains about libGL.so.1, either install libgl1 or switch to the headless package.

Anaconda or Miniconda. Conda manages Python and its binary libraries together. Create a clean environment, activate it and install OpenCV from conda-forge:

Terminal
conda create -n vision python=3.12 numpy
conda activate vision
conda install -c conda-forge opencv
python -c "import cv2; print(cv2.__version__)"

Do not run pip install opencv-python inside the same conda environment as the conda package, because two copies of cv2 fight over the same name. In Anaconda Navigator you can start Jupyter or Spyder from the environment you created, so notebooks see the same OpenCV.

Step 3: check the install

Save this as check_cv.py and run python check_cv.py:

Python
import cv2
import numpy as np

print("OpenCV version:", cv2.__version__)
print("NumPy version:", np.__version__)

# Build a tiny image and run one OpenCV function on it.
img = np.zeros((4, 4, 3), dtype=np.uint8)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print("gray shape:", gray.shape)

You should see a 4.x version string and gray shape: (4, 4). cv2.getBuildInformation() prints a long report of the compiled features (threads, video backends, GUI toolkit) if you ever need to know exactly what your build can do.

GUI versus headless errors

If you installed the wrong build, cv2.imshow fails at the first call. With a headless build you typically see an error saying the function is "not implemented" and mentioning GTK, Cocoa or Windows support. The fix is to uninstall and install the GUI package:

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

On the other side, if you only save results to files (no windows), the headless build works everywhere, including inside containers that have no display. Chapter 10 covers headless debugging in more detail.

Another classic error is ModuleNotFoundError: No module named 'cv2'. The package name (opencv-python) is not the import name (cv2), and the usual cause is installing into a different Python than the one that runs your script. Check with python -m pip show opencv-python using the same interpreter.

A stand-in: choosing the right package

The real install cannot run here, but the decision can. This helper turns your situation into a package name, which is a handy way to think about it.

Python Which package do I need?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A stand-in: reading a version string

cv2.__version__ is a plain string like 4.10.0. Real scripts sometimes compare it to a minimum. Never compare version strings with <, because "4.10.0" < "4.9.0" is True as text. Compare tuples of integers instead.

Python Comparing version strings correctly

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The text comparison says False because "1" sorts before "9" character by character, while the tuple comparison correctly says True. Dedicated packages such as packaging do this too, but a tuple of ints is enough for a quick check.

Keep a small check_cv.py in every new project. When something odd happens later, the first debugging step is always "which OpenCV is this, and where did it import from?" (print(cv2.__file__) answers the second question).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You are building a Docker image that only saves processed images to disk. Which package fits best?

    Headless has no GUI code, is smaller and works without a display. cv2 is the import name, not a package.
  2. 2. What happens if you install both opencv-python and opencv-python-headless in one environment?

    Both packages install the same cv2 module files, so they conflict. Install only one.
  3. 3. Why should you run pip as 'python -m pip'?

    Mixing up interpreters is a common reason for ModuleNotFoundError. python -m pip ties the install to the interpreter you named.
  4. 4. Which value is a safe way to compare OpenCV versions in code?

    As text, '4.10.0' sorts before '4.9.0'. Tuples of ints compare numerically.

Summary

  • Install exactly one of opencv-python, opencv-contrib-python or their -headless variants; all provide import cv2.
  • Use a virtual environment and python -m pip install opencv-python for learning.
  • Verify with cv2.__version__ and a small cvtColor call; use headless builds on servers.
  • Compare versions as integer tuples, not as strings.

Now that OpenCV is installed, learn what an image really is: Images Are NumPy Arrays.