Practice Now
opencv
pip install
computer vision
python library
programming tutorial

How do I install opencv using pip?

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
Computer VisionPython

Introduction

OpenCV for Python is installed via pip with pip install opencv-python. There are four PyPI packages available: opencv-python (main modules only), opencv-python-headless (no GUI, for servers), opencv-contrib-python (main + extra modules), and opencv-contrib-python-headless (extra modules, no GUI). For most use cases, pip install opencv-python is sufficient. For server environments or Docker containers without a display, use the -headless variant to avoid unnecessary GUI dependencies.

Basic Installation

bash
1# Standard OpenCV — most common choice
2pip install opencv-python
3
4# Verify installation
5python -c "import cv2; print(cv2.__version__)"
6# 4.9.0

This installs the main OpenCV modules including cv2.imread(), cv2.VideoCapture(), cv2.resize(), and most commonly used functions.

Choosing the Right Package

bash
1# Main modules only (most users)
2pip install opencv-python
3
4# Main modules, no GUI (servers, Docker, CI/CD)
5pip install opencv-python-headless
6
7# Main + extra/contrib modules (SIFT, SURF, etc.)
8pip install opencv-contrib-python
9
10# Main + extra, no GUI (servers needing extra modules)
11pip install opencv-contrib-python-headless
PackageGUI SupportExtra ModulesUse Case
opencv-pythonYesNoDesktop development
opencv-python-headlessNoNoServers, Docker
opencv-contrib-pythonYesYesResearch, SIFT/SURF
opencv-contrib-python-headlessNoYesServer-side research

Only install one of these four packages. Installing multiple causes conflicts.

bash
1# Create and activate a virtual environment
2python -m venv cv_env
3source cv_env/bin/activate   # Linux/macOS
4# cv_env\Scripts\activate    # Windows
5
6# Install OpenCV
7pip install opencv-python
8
9# Install with numpy (usually auto-installed as dependency)
10pip install opencv-python numpy

Installing a Specific Version

bash
1# Install a specific version
2pip install opencv-python==4.9.0.80
3
4# Install minimum version
5pip install "opencv-python>=4.8.0"
6
7# List available versions
8pip index versions opencv-python
9
10# Upgrade to latest
11pip install --upgrade opencv-python

Verify Installation

python
1import cv2
2import numpy as np
3
4# Check version
5print(f"OpenCV version: {cv2.__version__}")
6print(f"NumPy version: {np.__version__}")
7
8# List available modules
9print(dir(cv2))
10
11# Quick test: create and display an image
12img = np.zeros((300, 300, 3), dtype=np.uint8)
13cv2.rectangle(img, (50, 50), (250, 250), (0, 255, 0), 2)
14cv2.putText(img, "OpenCV Works!", (60, 170), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)
15
16# Only works with non-headless version
17# cv2.imshow("Test", img)
18# cv2.waitKey(0)
19
20# Save to file (works with all versions)
21cv2.imwrite("test_output.png", img)
22print("Image saved successfully")

Troubleshooting Common Installation Issues

ImportError: libGL.so.1

bash
1# On Ubuntu/Debian servers (missing OpenGL library)
2sudo apt-get update
3sudo apt-get install libgl1-mesa-glx
4
5# Or just use the headless version to avoid this entirely
6pip uninstall opencv-python
7pip install opencv-python-headless

Conflict Between Multiple OpenCV Packages

bash
1# Remove all OpenCV packages first
2pip uninstall opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
3
4# Then install only one
5pip install opencv-python

Permission Errors

bash
1# Use --user flag if you don't have admin access
2pip install --user opencv-python
3
4# Or use a virtual environment (preferred)
5python -m venv myenv
6source myenv/bin/activate
7pip install opencv-python

Python Version Compatibility

bash
1# Check your Python version
2python --version
3
4# OpenCV 4.x requires Python 3.6+
5# For older Python, install an older OpenCV version
6pip install "opencv-python<4.6"

Docker Installation

dockerfile
1FROM python:3.11-slim
2
3# Install headless OpenCV (no GUI dependencies needed)
4RUN pip install opencv-python-headless numpy
5
6# If you need the full version with GUI support:
7# RUN apt-get update && apt-get install -y libgl1-mesa-glx libglib2.0-0
8# RUN pip install opencv-python

Using with Jupyter Notebook

python
1# In a Jupyter cell
2import cv2
3import numpy as np
4from IPython.display import display, Image as IPImage
5import tempfile
6
7# Read an image
8img = cv2.imread("photo.jpg")
9
10# Display in Jupyter (convert BGR to RGB, encode as PNG)
11_, encoded = cv2.imencode('.png', img)
12display(IPImage(data=encoded.tobytes()))

Common Pitfalls

  • Installing multiple OpenCV packages simultaneously: Having both opencv-python and opencv-contrib-python installed causes import errors or unpredictable behavior. Uninstall all variants before installing the one you need.
  • Using opencv-python on a headless server: The full package requires GUI libraries (libGL, libSM, etc.) that are not available on servers. Use opencv-python-headless to avoid ImportError: libGL.so.1 errors.
  • Importing as opencv instead of cv2: The Python module name is cv2, not opencv. The pip package name opencv-python does not match the import name.
  • Missing NumPy dependency: OpenCV depends on NumPy. While pip usually installs it automatically, some environments (like minimal Docker images) may need pip install numpy separately if the dependency resolution fails.
  • Building from source unnecessarily: Pre-built wheels from PyPI work on most platforms (Windows, macOS, Linux x86_64). Building from source is only needed for ARM architectures, custom build flags, or CUDA GPU support.

Summary

  • Install with pip install opencv-python for most use cases
  • Use opencv-python-headless for servers, Docker, and CI/CD environments
  • Use opencv-contrib-python when you need extra modules like SIFT, SURF, or ArUco markers
  • Only install one OpenCV package at a time — uninstall others first
  • The Python import name is cv2, not opencv
  • Fix libGL.so.1 errors by installing system libraries or switching to the headless package
Related reading
Free course
Beginner
7 lessons
2 hours
Tackling System Design Interview Problems

A short course that equips you with the skills to approach system design interviews methodically.

Start the free course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.