{"id":671,"library":"opencv-python","title":"OpenCV Python Bindings","description":"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.","status":"active","version":"4.13.0.92","language":"python","source_language":"en","source_url":"https://github.com/opencv/opencv-python","tags":["computer vision","image processing","video processing","AI"],"install":[{"cmd":"pip install opencv-python","lang":"bash","label":"Install core OpenCV with GUI support"}],"dependencies":[{"reason":"Essential for image and array manipulations, as OpenCV images are represented as NumPy arrays.","package":"numpy","optional":false}],"imports":[{"note":"The Python binding module is named `cv2` for historical reasons, not `opencv` or `cv`.","wrong":"import opencv","symbol":"cv2","correct":"import cv2"}],"quickstart":{"code":"import cv2\nimport os\n\n# Create a dummy image file for demonstration\n# In a real scenario, replace 'test_image.jpg' with your image path.\nimg_placeholder_path = 'test_image.jpg'\nif not os.path.exists(img_placeholder_path):\n    try:\n        import numpy as np\n        dummy_img = np.zeros((300, 500, 3), dtype=np.uint8)\n        cv2.putText(dummy_img, \"Hello OpenCV\", (50, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)\n        cv2.imwrite(img_placeholder_path, dummy_img)\n        print(f\"Created dummy image: {img_placeholder_path}\")\n    except ImportError:\n        print(\"NumPy not found. Cannot create dummy image. Please ensure 'test_image.jpg' exists.\")\n\n# Load an image from file\nimg = cv2.imread(img_placeholder_path, cv2.IMREAD_COLOR)\n\n# Check if image loading was successful\nif img is None:\n    print(f\"Error: Could not load image from {img_placeholder_path}. Please ensure the file exists and is accessible.\")\nelse:\n    # Display the image in a window\n    cv2.imshow('My Image', img)\n\n    # Wait indefinitely until a key is pressed\n    cv2.waitKey(0)\n\n    # Close all OpenCV windows\n    cv2.destroyAllWindows()\n\n    # Optionally, save the processed image\n    # cv2.imwrite('output_image.jpg', img)\n    \n    # Clean up dummy image if created\n    if os.path.exists(img_placeholder_path) and 'dummy_img' in locals():\n        os.remove(img_placeholder_path)\n        print(f\"Cleaned up dummy image: {img_placeholder_path}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"OpenCV-Python versions compiled with NumPy 1.x are not binary compatible with NumPy 2.x, leading to `ImportError` or runtime crashes.","severity":"breaking","affected_versions":"<4.10.0.84, <4.12.0.88 for some Python versions"},{"fix":"For headless environments, use `pip install opencv-python-headless` instead. This package provides core OpenCV functionality without the GUI components.","message":"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'.","severity":"gotcha","affected_versions":"All versions of `opencv-python`"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Convert the image from BGR to RGB using `cv2.cvtColor(img, cv2.COLOR_BGR2RGB)` before displaying it with RGB-expecting libraries.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the necessary build tools and C/C++ compilers are installed on the system *before* attempting `pip install opencv-python`. For `alpine` Linux, this typically involves `apk add python3-dev build-base cmake ninja`. Alternatively, use a base image for which pre-built `opencv-python` wheels are available (e.g., Debian/Ubuntu), or consider using `opencv-python-headless` which might have fewer build dependencies.","message":"Building `opencv-python` from source, especially on `alpine` Linux, often fails due to missing C/C++ compilers and essential build tools (like `cmake`, `ninja`, or `make`). The `scikit-build` system used by `opencv-python` explicitly states it cannot install these dependencies on `alpine`.","severity":"breaking","affected_versions":"All versions (when building from source on Alpine)"}],"env_vars":null,"last_verified":"2026-05-12T17:43:00.030Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure you install the correct package in your active Python environment: `pip install opencv-python` or `pip install opencv-contrib-python` for extra modules.","cause":"This error occurs because the `opencv-python` package, which provides the `cv2` module, is either not installed in your current Python environment, or was installed using the incorrect package name `cv2` instead of `opencv-python`.","error":"ModuleNotFoundError: No module named 'cv2'"},{"fix":"Verify Python and `opencv-python` version compatibility, upgrade `pip` (`python -m pip install --upgrade pip`), consider installing `opencv-python-headless` if GUI components are not needed, or ensure the necessary Visual C++ Redistributables are installed and updated. Sometimes, a complete uninstall and reinstall of `opencv-python` resolves the issue.","cause":"(Windows-specific) This typically indicates that required Dynamic Link Libraries (DLLs) that OpenCV depends on are either missing, incompatible with your Python version, or cannot be found in your system's PATH. This can also be caused by conflicts with other installed libraries or an incomplete installation.","error":"ImportError: DLL load failed while importing cv2"},{"fix":"First, check if you have a file named `cv2.py` in your project directory and rename it. If the error persists for basic functions, uninstall `opencv-python` and reinstall it. If it's for an advanced module, install `opencv-contrib-python`: `pip install opencv-contrib-python`.","cause":"This error usually means that the `opencv-python` installation is incomplete, corrupted, or shadowed by a local file named `cv2.py`. If the attribute is for a specialized module (e.g., `face`), it indicates that the `opencv-contrib-python` package (which includes additional modules) is not installed.","error":"AttributeError: module 'cv2' has no attribute 'imread'"},{"fix":"Use the correct package name for installation: `pip install opencv-python` or `pip install opencv-contrib-python` if you need extra modules.","cause":"This is a common mistake where developers attempt to install the package using `cv2`, the module's import name, instead of the correct PyPI package name, `opencv-python`. This command will fail to install the library and subsequently lead to a `ModuleNotFoundError`.","error":"pip install cv2"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"4.13.0.92","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.6,"import_time_s":null,"mem_mb":null,"disk_size":"277M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.3,"import_time_s":null,"mem_mb":null,"disk_size":"284M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.2,"import_time_s":null,"mem_mb":null,"disk_size":"272M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.2,"import_time_s":null,"mem_mb":null,"disk_size":"272M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.5,"import_time_s":null,"mem_mb":null,"disk_size":"287M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}