OpenCV Python Bindings

4.13.0.92 · active · verified Sat Mar 28

OpenCV (Open Source Computer Vision Library) is a highly optimized open-source library for computer vision and machine learning tasks. The `opencv-python` package provides official Python bindings, enabling developers to access its extensive functionalities for image and video processing, object detection, and more within Python applications. It is actively maintained with frequent minor releases, often on a monthly cadence, to incorporate new features, bug fixes, and support for the latest Python and NumPy versions.

Warnings

breaking OpenCV-Python versions compiled with NumPy 1.x are not binary compatible with NumPy 2.x, leading to `ImportError` or runtime crashes.
Fix: Upgrade `opencv-python` to version 4.10.0.84 or later (or the latest available version that explicitly supports NumPy 2.x for your Python version). Alternatively, downgrade NumPy to a version less than 2.0 (`pip install "numpy<2.0"`) if upgrading OpenCV is not an option.
gotcha Using `opencv-python` (which includes GUI dependencies like Qt/X11) in headless environments (e.g., Docker containers, remote servers without a display) can cause runtime errors such as 'Cannot connect to X server'.
Fix: For headless environments, use `pip install opencv-python-headless` instead. This package provides core OpenCV functionality without the GUI components.
gotcha Functions like `cv2.imread()` or `cv2.VideoCapture().read()` return `None` if the file path is incorrect/inaccessible or if a frame cannot be read, respectively. Subsequent operations on this `None` object will raise `AttributeError: 'NoneType' object has no attribute 'something'` or `cv2.error: (-215:Assertion failed) !_src.empty()`.
Fix: Always check if the returned object (e.g., `img` from `cv2.imread()`, `success` from `cap.read()`) is valid (not `None` or `False`) before proceeding with image/frame processing.
gotcha There are several `opencv-python` package variants (`opencv-python`, `opencv-contrib-python`, `opencv-python-headless`, `opencv-contrib-python-headless`). Installing the wrong one can lead to missing features (e.g., SIFT, SURF algorithms are in `opencv-contrib-python` due to patent restrictions) or unnecessary GUI dependencies.
Fix: Choose the correct package for your needs: `opencv-python` for core modules with GUI, `opencv-contrib-python` for core + extra modules with GUI, `opencv-python-headless` for core modules without GUI, and `opencv-contrib-python-headless` for core + extra modules without GUI. Do not install multiple variants in the same environment.
gotcha OpenCV by default loads images in BGR (Blue-Green-Red) color order, while many other Python libraries (e.g., Matplotlib, Pillow) expect RGB (Red-Green-Blue). Directly displaying an OpenCV-loaded image with an RGB-expecting library will result in incorrect colors.
Fix: Convert the image from BGR to RGB using `cv2.cvtColor(img, cv2.COLOR_BGR2RGB)` before displaying it with RGB-expecting libraries.

Install

pip install opencv-python Install core OpenCV with GUI support

Imports

cv2
```
import cv2
```
The Python binding module is named `cv2` for historical reasons, not `opencv` or `cv`.

Quickstart

This quickstart demonstrates how to load, display, and then close an image using `opencv-python`. It includes error handling for failed image loading and ensures proper window closure. A dummy image is created if 'test_image.jpg' does not exist.

import cv2
import os

# Create a dummy image file for demonstration
# In a real scenario, replace 'test_image.jpg' with your image path.
img_placeholder_path = 'test_image.jpg'
if not os.path.exists(img_placeholder_path):
    try:
        import numpy as np
        dummy_img = np.zeros((300, 500, 3), dtype=np.uint8)
        cv2.putText(dummy_img, "Hello OpenCV", (50, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
        cv2.imwrite(img_placeholder_path, dummy_img)
        print(f"Created dummy image: {img_placeholder_path}")
    except ImportError:
        print("NumPy not found. Cannot create dummy image. Please ensure 'test_image.jpg' exists.")

# Load an image from file
img = cv2.imread(img_placeholder_path, cv2.IMREAD_COLOR)

# Check if image loading was successful
if img is None:
    print(f"Error: Could not load image from {img_placeholder_path}. Please ensure the file exists and is accessible.")
else:
    # Display the image in a window
    cv2.imshow('My Image', img)

    # Wait indefinitely until a key is pressed
    cv2.waitKey(0)

    # Close all OpenCV windows
    cv2.destroyAllWindows()

    # Optionally, save the processed image
    # cv2.imwrite('output_image.jpg', img)
    
    # Clean up dummy image if created
    if os.path.exists(img_placeholder_path) and 'dummy_img' in locals():
        os.remove(img_placeholder_path)
        print(f"Cleaned up dummy image: {img_placeholder_path}")

view raw JSON →