Installing OpenCV

Installation Overview

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

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

Quick Install

For rapid setup, use these package managers:

Python
Linux
macOS
Windows

# Using pip
pip install opencv-python

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

# Using conda
conda install -c conda-forge opencv

The opencv-python package includes prebuilt binaries for most platforms and is the easiest way to get started with Python.

# 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

# Using Homebrew
brew install opencv

# Using pip
pip install opencv-python

# Using pip
pip install opencv-python

# Or download prebuilt binaries from:
# https://github.com/opencv/opencv/releases

Building from Source

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

Prerequisites

Install Build Tools

Install a C++ compiler and build tools for your platform:Linux:

# 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:

xcode-select --install

Install CMake

CMake 3.9 or higher is required:

# Linux (Ubuntu/Debian)
sudo apt-get install cmake

# macOS
brew install cmake

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

Verify installation:

cmake --version

Install Git

Required to download OpenCV source:

# Linux (Ubuntu/Debian)
sudo apt-get install git

# macOS (if not already installed)
brew install git

# Windows: Download from https://git-scm.com/

Download OpenCV Source

# 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

# 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

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

Platform-Specific Build Instructions

Linux
Windows
macOS

Building on Linux

Install Dependencies

# 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

Configure Build

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 \
      ..

Use cmake -DCMAKE_BUILD_TYPE=Release for optimized builds. Use Debug for development.

Compile

# Build using all CPU cores
make -j$(nproc)

# This may take 15-60 minutes depending on your system

Install

# 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

Verify Installation

# Check OpenCV version
pkg-config --modversion opencv4

# Test Python bindings
python3 -c "import cv2; print(cv2.__version__)"

Building on Windows

Install Visual Studio

Download and install Visual Studio 2015 or later:

Community Edition (free): https://visualstudio.microsoft.com/
Select “Desktop development with C++” workload

Install CMake and Git

CMake: https://cmake.org/download/
Git: https://git-scm.com/download/win

During CMake installation, select “Add CMake to system PATH for all users”

Clone OpenCV

Open Git Bash or Command Prompt:

cd C:\\lib
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

Configure with CMake GUI

Open CMake GUI
Set source directory: C:/lib/opencv
Set build directory: C:/lib/opencv/build
Click “Configure” and select your Visual Studio version
Set configuration options:
- OPENCV_EXTRA_MODULES_PATH: C:/lib/opencv_contrib/modules
- BUILD_EXAMPLES: ON
- BUILD_opencv_python3: ON (if you want Python support)
Click “Generate”

Build

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

Set Environment Variables

Add OpenCV to system PATH:

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

Building on macOS

Install Xcode Command Line Tools

xcode-select --install

Install CMake

# Using Homebrew (recommended)
brew install cmake

# Or download from https://cmake.org/download/

Clone OpenCV

cd ~/workspace
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

Configure and Build

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)

Install

# Install system-wide
sudo make install

# Update library cache
sudo update_dyld_shared_cache

Verify Installation

# Check version
python3 -c "import cv2; print(cv2.__version__)"

# Test in C++
pkg-config --cflags --libs opencv4

Configuration Options

Customize your OpenCV build with these CMake options:

Common Options

# 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

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

Language-Specific Setup

Python

Verify Python bindings:

import cv2
print(f"OpenCV version: {cv2.__version__}")
print(f"Build info:\n{cv2.getBuildInformation()}")

C++

Create a CMakeLists.txt for your project:

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:

// Load native library
System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

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

Troubleshooting

CMake cannot find dependencies

Install missing packages or specify paths manually:

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 \
      ..

Build fails with memory errors

Reduce parallel jobs:

make -j2  # Use only 2 cores instead of all

Python can't find cv2 module

Check installation path:

import sys
print(sys.path)

Add OpenCV to Python path:

export PYTHONPATH=$PYTHONPATH:/usr/local/lib/python3.8/site-packages

Windows DLL errors

Ensure OpenCV bin directory is in PATH:

echo %PATH%

Copy DLLs to your application directory as a workaround.

If you encounter errors, check the OpenCV forum or GitHub issues for solutions.

Next Steps

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

Quickstart Guide

Build your first OpenCV application with step-by-step examples

​Installation Overview

​Quick Install

​Building from Source

​Prerequisites

​Download OpenCV Source

​Platform-Specific Build Instructions

​Building on Linux

​Verify Installation

​Building on Windows

​Building on macOS

​Verify Installation

​Configuration Options

​Common Options

​Language-Specific Setup

​Python

​C++

​Java

​Troubleshooting

​Next Steps

Quickstart Guide

Installation Overview

Quick Install

Building from Source

Prerequisites

Download OpenCV Source

Platform-Specific Build Instructions

Building on Linux

Verify Installation

Building on Windows

Building on macOS

Verify Installation

Configuration Options

Common Options

Language-Specific Setup

Python

C++

Java

Troubleshooting

Next Steps