DOCSEARCHbyAlgolia
Submit Docs

opencv-python

repository·4.x·Indexed 26 days ago

https://github.com/opencv/opencv-python

Python bindings for the OpenCV library. Provides pre-built wheels for standard desktops and headless servers (Docker/Cloud), including main and contrib/extra modules. Includes documentation on installation via pip, manual wheel building, debug mode configuration, and troubleshooting DLL load failures on Windows.

Tokens
1.6K
Snippets
2
Records
9
Agent score
40%

What's inside opencv-python

  1. Install opencv-python via pip

    4.x

    To install pre-built CPU-only OpenCV packages, use pip.

    Important Prerequisites:

    1. Remove existing manual installations: If you have a cv2 module manually installed in your Python site-packages (not via pip), remove it first to avoid conflicts.
    2. Upgrade pip: Ensure your pip version is at least 19.3. Use pip install --upgrade pip.
    3. Select ONLY ONE package: All packages share the same cv2 namespace. Installing multiple packages in the same environment will cause conflicts. Uninstall all existing versions before installing a new one.

    Package Options:

    | Environment Type | Package Name | Description | | :--- | :--- | : | | Standard Desktop (Windows, macOS, Linux) | opencv-python | Main modules only | | | opencv-contrib-python | Main modules + contrib/extra modules | | Server/Headless (Docker, Cloud, no GUI) | opencv-python-headless | Main modules, no GUI dependencies | | | opencv-contrib-python-headless | Main modules + contrib/extra, no GUI dependencies |

    Note: Use headless packages if you do not use cv2.imshow or if you use another library (like PyQt) for your GUI to keep Docker images small and avoid X11 dependencies.

  2. Force pip to build from source distribution

    4.x
    If your system is incompatible with available wheels, pip will attempt to build from source. You can explicitly force this behavior using the --no-binary flag. This is useful if you need to pass custom CMAKE_ARGS via environment variables during the installation process.

  3. Build opencv-python in debug mode

    4.x

    To create an unoptimized debug build of opencv-python, follow these steps:

    1. Install required dependencies: pip install scikit-build numpy.
    2. Run the build command with the debug type: python setup.py bdist_wheel --build-type=Debug.
    3. Install the resulting wheel from the dist/ folder using pip install.

    To generate all compiler commands (useful for debugging builds on Linux), use the following environment variables:

    • CMAKE_ARGS='-DCMAKE_VERBOSE_MAKEFILE=ON'
    • VERBOSE=1
    # For a standard debug build
python setup.py bdist_wheel --build-type=Debug

# For a debug build with full compiler command output (Linux)
export CMAKE_ARGS='-DCMAKE_VERBOSE_MAKEFILE=ON'
export VERBOSE=1
python3 setup.py bdist_wheel --build-type=Debug

  4. Build opencv-python wheels manually

    4.x

    If pre-built wheels do not meet your dependency requirements, you can build a custom wheel locally. This process requires cloning the repository recursively to include OpenCV and Contrib submodules.

    To build a standard wheel:

    1. Clone the repository: git clone --recursive https://github.com/opencv/opencv-python.git
    2. Navigate to the directory: cd opencv-python
    3. (Optional) Set custom CMake flags via the CMAKE_ARGS environment variable.
    4. (Optional) Select a package flavor by setting ENABLE_CONTRIB=1 (for contrib modules) or ENABLE_HEADLESS=1 (for headless version).
    5. Run pip wheel . --verbose to generate the wheel.

    Note: Build times vary from 5 minutes to over 2 hours depending on hardware. For maximum portability on Linux, use manylinux Docker images and run auditwheel on the resulting wheel. On macOS, use delocate.

    git clone --recursive https://github.com/opencv/opencv-python.git
cd opencv-python
export CMAKE_ARGS="-DSOME_FLAG=ON"
export ENABLE_CONTRIB=1
pip wheel . --verbose

  5. Troubleshoot Windows ImportError: DLL load failed

    4.x

    If you encounter ImportError: DLL load failed: The specified module could not be found. on Windows, follow these steps:

    1. Install Visual C++ Redistributable: Ensure Visual C++ redistributable 2015 is installed.
    2. Install Universal C Runtime: For older Windows versions (pre-Windows 10), install the Universal C Runtime.
    3. Media Feature Pack:
      • If using Windows N or KN editions, install the Windows Media Feature Pack.
      • If using Windows Server 2012+, install the "Media Foundation" feature via Server Manager.
    4. Anaconda Users: If using an old Anaconda version, check for known bugs regarding DLL loading.
    5. Debug Missing DLLs: Use the Dependencies tool to open the cv2.pyd file (found in your site-packages/cv2 directory) to identify exactly which DLL is missing.

  6. Troubleshoot pip installation failure (ModuleNotFoundError: No module named 'skbuild')

    4.x

    If pip install fails with ModuleNotFoundError: No module named 'skbuild', it is likely because your pip version is too old to recognize manylinux2014 wheels. This causes pip to attempt a manual source build which then fails because it cannot process the pyproject.toml build dependencies.

    Solution: Upgrade pip to version 19.3 or higher:

    pip install --upgrade pip

  9. Custom build environment variables

    4.x

    When building opencv-python (via pip wheel or setup.py), you can use the following environment variables to customize the build:

    VariableDescription
    CMAKE_ARGSAdditional arguments passed to OpenCV's CMake invocation. Use this for custom builds (e.g., -DSOME_FLAG=ON).
    ENABLE_CONTRIBSet to 1 to build the opencv-contrib-python version.
    ENABLE_HEADLESSSet to 1 to build the headless version (disables GUI dependencies).
    ENABLE_JAVASet to 1 to enable the Java client build (disabled by default).
    CI_BUILDSet to 1 to emulate CI environment behavior. Warning: Do not use unless you know what you are doing.