> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencv/opencv/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing OpenCV

> Complete installation guide for OpenCV on Linux, Windows, and macOS with support for C++, Python, and Java

## Installation Overview

OpenCV can be installed in two ways: using prebuilt binaries or building from source. This guide covers both methods across different platforms.

<Note>
  For most users, especially Python developers, using prebuilt packages (pip, conda, or system package managers) is the quickest way to get started.
</Note>

## Quick Install

For rapid setup, use these package managers:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    # Using pip
    pip install opencv-python

    # With contrib modules (extra features)
    pip install opencv-contrib-python

    # Using conda
    conda install -c conda-forge opencv
    ```

    <Tip>
      The `opencv-python` package includes prebuilt binaries for most platforms and is the easiest way to get started with Python.
    </Tip>
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt-get update
    sudo apt-get install libopencv-dev python3-opencv

    # Fedora
    sudo dnf install opencv opencv-devel python3-opencv

    # Arch Linux
    sudo pacman -S opencv
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # Using Homebrew
    brew install opencv

    # Using pip
    pip install opencv-python
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # Using pip
    pip install opencv-python

    # Or download prebuilt binaries from:
    # https://github.com/opencv/opencv/releases
    ```
  </Tab>
</Tabs>

## Building from Source

Building OpenCV from source gives you full control over features, optimizations, and dependencies.

### Prerequisites

<Steps>
  <Step title="Install Build Tools">
    Install a C++ compiler and build tools for your platform:

    **Linux:**

    ```bash theme={null}
    # GCC/G++
    sudo apt-get install build-essential

    # Or Clang
    sudo apt-get install clang
    ```

    **Windows:**

    * Visual Studio 2015 or later (Community Edition is free)
    * Or MinGW-w64 compiler

    **macOS:**

    ```bash theme={null}
    xcode-select --install
    ```
  </Step>

  <Step title="Install CMake">
    CMake 3.9 or higher is required:

    ```bash theme={null}
    # Linux (Ubuntu/Debian)
    sudo apt-get install cmake

    # macOS
    brew install cmake

    # Windows: Download from https://cmake.org/download/
    ```

    Verify installation:

    ```bash theme={null}
    cmake --version
    ```
  </Step>

  <Step title="Install Git">
    Required to download OpenCV source:

    ```bash theme={null}
    # Linux (Ubuntu/Debian)
    sudo apt-get install git

    # macOS (if not already installed)
    brew install git

    # Windows: Download from https://git-scm.com/
    ```
  </Step>
</Steps>

### Download OpenCV Source

<CodeGroup>
  ```bash Git Clone theme={null}
  # Clone main repository
  git clone https://github.com/opencv/opencv.git
  cd opencv
  git checkout 4.x  # or specific version like 4.8.0

  # Optional: Clone contrib modules
  cd ..
  git clone https://github.com/opencv/opencv_contrib.git
  cd opencv_contrib
  git checkout 4.x  # must match opencv version
  ```

  ```bash Download Archive theme={null}
  # Download from GitHub releases
  wget https://github.com/opencv/opencv/archive/4.x.zip
  unzip 4.x.zip

  # Optional: Download contrib modules
  wget https://github.com/opencv/opencv_contrib/archive/4.x.zip
  unzip 4.x.zip
  ```
</CodeGroup>

<Warning>
  When using both `opencv` and `opencv_contrib`, ensure both repositories are at the same version/tag to avoid compatibility issues.
</Warning>

## Platform-Specific Build Instructions

<Tabs>
  <Tab title="Linux">
    ### Building on Linux

    <Steps>
      <Step title="Install Dependencies">
        ```bash theme={null}
        # Required dependencies
        sudo apt-get install build-essential cmake git pkg-config \
          libgtk-3-dev libavcodec-dev libavformat-dev libswscale-dev \
          libv4l-dev libxvidcore-dev libx264-dev libjpeg-dev libpng-dev \
          libtiff-dev gfortran openexr libatlas-base-dev python3-dev \
          python3-numpy libtbb2 libtbb-dev libdc1394-22-dev

        # Optional: for Python bindings
        pip install numpy
        ```
      </Step>

      <Step title="Configure Build">
        ```bash theme={null}
        cd opencv
        mkdir build && cd build

        # Basic configuration
        cmake -DCMAKE_BUILD_TYPE=Release \
              -DCMAKE_INSTALL_PREFIX=/usr/local \
              -DBUILD_EXAMPLES=ON \
              ..

        # With contrib modules
        cmake -DCMAKE_BUILD_TYPE=Release \
              -DCMAKE_INSTALL_PREFIX=/usr/local \
              -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
              -DBUILD_EXAMPLES=ON \
              ..
        ```

        <Tip>
          Use `cmake -DCMAKE_BUILD_TYPE=Release` for optimized builds. Use `Debug` for development.
        </Tip>
      </Step>

      <Step title="Compile">
        ```bash theme={null}
        # Build using all CPU cores
        make -j$(nproc)

        # This may take 15-60 minutes depending on your system
        ```
      </Step>

      <Step title="Install">
        ```bash theme={null}
        # Install to system directories (requires sudo)
        sudo make install
        sudo ldconfig
        ```

        Installation locations:

        * Binaries: `/usr/local/bin`
        * Libraries: `/usr/local/lib`
        * Headers: `/usr/local/include/opencv4`
        * CMake config: `/usr/local/lib/cmake/opencv4`
      </Step>
    </Steps>

    ### Verify Installation

    ```bash theme={null}
    # Check OpenCV version
    pkg-config --modversion opencv4

    # Test Python bindings
    python3 -c "import cv2; print(cv2.__version__)"
    ```
  </Tab>

  <Tab title="Windows">
    ### Building on Windows

    <Steps>
      <Step title="Install Visual Studio">
        Download and install Visual Studio 2015 or later:

        * Community Edition (free): [https://visualstudio.microsoft.com/](https://visualstudio.microsoft.com/)
        * Select "Desktop development with C++" workload
      </Step>

      <Step title="Install CMake and Git">
        * CMake: [https://cmake.org/download/](https://cmake.org/download/)
        * Git: [https://git-scm.com/download/win](https://git-scm.com/download/win)

        <Note>
          During CMake installation, select "Add CMake to system PATH for all users"
        </Note>
      </Step>

      <Step title="Clone OpenCV">
        Open Git Bash or Command Prompt:

        ```bash theme={null}
        cd C:\\lib
        git clone https://github.com/opencv/opencv.git
        git clone https://github.com/opencv/opencv_contrib.git
        ```
      </Step>

      <Step title="Configure with CMake GUI">
        1. Open CMake GUI
        2. Set source directory: `C:/lib/opencv`
        3. Set build directory: `C:/lib/opencv/build`
        4. Click "Configure" and select your Visual Studio version
        5. Set configuration options:
           * `OPENCV_EXTRA_MODULES_PATH`: `C:/lib/opencv_contrib/modules`
           * `BUILD_EXAMPLES`: ON
           * `BUILD_opencv_python3`: ON (if you want Python support)
        6. Click "Generate"
      </Step>

      <Step title="Build">
        ```cmd theme={null}
        cd C:\\lib\\opencv\\build

        REM Build Release version
        cmake --build . --config Release

        REM Build Debug version
        cmake --build . --config Debug

        REM Install (optional)
        cmake --build . --target install --config Release
        ```
      </Step>

      <Step title="Set Environment Variables">
        Add OpenCV to system PATH:

        ```cmd theme={null}
        setx OpenCV_DIR C:\\lib\\opencv\\build\\x64\\vc16
        setx PATH "%PATH%;%OpenCV_DIR%\\bin"
        ```

        Replace `vc16` with your Visual Studio version:

        * VS 2015: vc14
        * VS 2017: vc15
        * VS 2019: vc16
        * VS 2022: vc17
      </Step>
    </Steps>
  </Tab>

  <Tab title="macOS">
    ### Building on macOS

    <Steps>
      <Step title="Install Xcode Command Line Tools">
        ```bash theme={null}
        xcode-select --install
        ```
      </Step>

      <Step title="Install CMake">
        ```bash theme={null}
        # Using Homebrew (recommended)
        brew install cmake

        # Or download from https://cmake.org/download/
        ```
      </Step>

      <Step title="Clone OpenCV">
        ```bash theme={null}
        cd ~/workspace
        git clone https://github.com/opencv/opencv.git
        git clone https://github.com/opencv/opencv_contrib.git
        ```
      </Step>

      <Step title="Configure and Build">
        ```bash theme={null}
        cd opencv
        mkdir build && cd build

        # Configure
        cmake -DCMAKE_BUILD_TYPE=Release \
              -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
              -DBUILD_EXAMPLES=ON \
              -DPYTHON3_EXECUTABLE=$(which python3) \
              ..

        # Build using all CPU cores
        make -j$(sysctl -n hw.ncpu)
        ```
      </Step>

      <Step title="Install">
        ```bash theme={null}
        # Install system-wide
        sudo make install

        # Update library cache
        sudo update_dyld_shared_cache
        ```
      </Step>
    </Steps>

    ### Verify Installation

    ```bash theme={null}
    # Check version
    python3 -c "import cv2; print(cv2.__version__)"

    # Test in C++
    pkg-config --cflags --libs opencv4
    ```
  </Tab>
</Tabs>

## Configuration Options

Customize your OpenCV build with these CMake options:

### Common Options

```bash theme={null}
# Performance optimizations
-DENABLE_FAST_MATH=ON
-DWITH_TBB=ON              # Threading Building Blocks
-DWITH_OPENMP=ON           # OpenMP support
-DWITH_IPP=ON              # Intel Performance Primitives

# Hardware acceleration
-DWITH_CUDA=ON             # NVIDIA CUDA support
-DWITH_OPENCL=ON           # OpenCL support

# Module options
-DBUILD_EXAMPLES=ON        # Build example applications
-DBUILD_TESTS=OFF          # Skip tests (faster build)
-DBUILD_PERF_TESTS=OFF     # Skip performance tests
-DBUILD_DOCS=ON            # Build documentation

# Language bindings
-DBUILD_opencv_python3=ON  # Python 3 bindings
-DBUILD_opencv_java=ON     # Java bindings

# Extra modules
-DOPENCV_EXTRA_MODULES_PATH=/path/to/opencv_contrib/modules
```

<Tip>
  For a list of all available options, run `cmake -L` in your build directory after initial configuration.
</Tip>

## Language-Specific Setup

### Python

Verify Python bindings:

```python theme={null}
import cv2
print(f"OpenCV version: {cv2.__version__}")
print(f"Build info:\n{cv2.getBuildInformation()}")
```

### C++

Create a CMakeLists.txt for your project:

```cmake theme={null}
cmake_minimum_required(VERSION 3.9)
project(MyOpenCVApp)

find_package(OpenCV REQUIRED)
include_directories(${OpenCV_INCLUDE_DIRS})

add_executable(myapp main.cpp)
target_link_libraries(myapp ${OpenCV_LIBS})
```

### Java

Add OpenCV to your Java project:

```java theme={null}
// Load native library
System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

// Verify installation
System.out.println("OpenCV version: " + Core.VERSION);
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="CMake cannot find dependencies">
    Install missing packages or specify paths manually:

    ```bash theme={null}
    cmake -DPYTHON3_EXECUTABLE=/usr/bin/python3 \
          -DPYTHON3_INCLUDE_DIR=/usr/include/python3.8 \
          -DPYTHON3_NUMPY_INCLUDE_DIRS=/usr/local/lib/python3.8/site-packages/numpy/core/include \
          ..
    ```
  </Accordion>

  <Accordion title="Build fails with memory errors">
    Reduce parallel jobs:

    ```bash theme={null}
    make -j2  # Use only 2 cores instead of all
    ```
  </Accordion>

  <Accordion title="Python can't find cv2 module">
    Check installation path:

    ```python theme={null}
    import sys
    print(sys.path)
    ```

    Add OpenCV to Python path:

    ```bash theme={null}
    export PYTHONPATH=$PYTHONPATH:/usr/local/lib/python3.8/site-packages
    ```
  </Accordion>

  <Accordion title="Windows DLL errors">
    Ensure OpenCV bin directory is in PATH:

    ```cmd theme={null}
    echo %PATH%
    ```

    Copy DLLs to your application directory as a workaround.
  </Accordion>
</AccordionGroup>

<Warning>
  If you encounter errors, check the [OpenCV forum](https://forum.opencv.org) or [GitHub issues](https://github.com/opencv/opencv/issues) for solutions.
</Warning>

## Next Steps

Now that OpenCV is installed, you're ready to write your first computer vision application!

<Card title="Quickstart Guide" icon="rocket" href="/quickstart">
  Build your first OpenCV application with step-by-step examples
</Card>