Building OpenCV on Linux

Complete guide for building and installing OpenCV on Linux distributions with various compilers and configurations

OpenCV provides comprehensive support for Linux platforms across multiple architectures including x86, x86_64, ARM, RISC-V, and more.

Quick Start

Get up and running with OpenCV on Linux in a few minutes:

1. Install Dependencies

   Install compiler, build tools, and CMake:

   # Debian/Ubuntu
   sudo apt update
   sudo apt install build-essential cmake git pkg-config
   
   # Fedora/RHEL
   sudo dnf install gcc gcc-c++ cmake git
   
   # Arch Linux
   sudo pacman -S base-devel cmake git
   
2. Download OpenCV

   Get the source code from GitHub:

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

   Or download a release archive:

   wget -O opencv.zip https://github.com/opencv/opencv/archive/4.x.zip
   unzip opencv.zip
   cd opencv-4.x
   
3. Build OpenCV

   Configure and compile:

   mkdir build && cd build
   cmake -DCMAKE_BUILD_TYPE=Release ..
   make -j$(nproc)
   
4. Install

   Install to system directories (optional):

   sudo make install
   

Compiler Support

OpenCV supports multiple compilers on Linux:

GCC

GCC is the default compiler on most Linux systems:

# Install GCC
sudo apt install gcc g++

# Verify version (5.x or later required)
gcc --version

# Build with GCC (default)
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

Clang

Clang offers faster compilation and better diagnostics:

# Install Clang
sudo apt install clang

# Configure to use Clang
cmake -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_BUILD_TYPE=Release \
      ..
make -j$(nproc)

Build System Options

Make (Default)

Traditional GNU Make build system:

cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

The -j$(nproc) flag enables parallel compilation using all CPU cores.

Ninja

Ninja is faster than Make for large projects:

# Install Ninja
sudo apt install ninja-build

# Configure for Ninja
cmake -GNinja -DCMAKE_BUILD_TYPE=Release ..
ninja

Ninja automatically detects and uses all available CPU cores.

Installing Dependencies

Required Dependencies

# Debian/Ubuntu - Minimal build
sudo apt install build-essential cmake git

# Debian/Ubuntu - With common features
sudo apt 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-dev

Optional Dependencies

GUI Support (highgui module)

# GTK+ 3 (recommended)
sudo apt install libgtk-3-dev

# Qt5 (alternative)
sudo apt install qtbase5-dev qttools5-dev

Video I/O Support

# FFmpeg libraries
sudo apt install libavcodec-dev libavformat-dev libswscale-dev

# GStreamer
sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

# V4L (Video4Linux)
sudo apt install libv4l-dev v4l-utils

Image Codecs

sudo apt install libjpeg-dev libpng-dev libtiff-dev \
                 libwebp-dev libopenexr-dev

Python Support

sudo apt install python3-dev python3-numpy python3-pip

Parallel Processing

# Intel TBB (Threading Building Blocks)
sudo apt install libtbb-dev

# OpenMP (usually included with GCC)
# Already available with gcc package

Cross-Compilation

OpenCV provides toolchain files for cross-compilation to other architectures:

ARM 32-bit (ARMv7)

# Install cross-compiler
sudo apt install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf

# Configure with toolchain file
cmake -DCMAKE_TOOLCHAIN_FILE=../platforms/linux/arm-gnueabi.toolchain.cmake \
      -DCMAKE_BUILD_TYPE=Release \
      ..
make -j$(nproc)

ARM 64-bit (AArch64)

# Install cross-compiler
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# Configure with toolchain file
cmake -DCMAKE_TOOLCHAIN_FILE=../platforms/linux/aarch64-gnu.toolchain.cmake \
      -DCMAKE_BUILD_TYPE=Release \
      ..
make -j$(nproc)

RISC-V 64-bit

# Install RISC-V toolchain
sudo apt install gcc-riscv64-linux-gnu g++-riscv64-linux-gnu

# Configure with toolchain file
cmake -DCMAKE_TOOLCHAIN_FILE=../platforms/linux/riscv64-gcc.toolchain.cmake \
      -DCMAKE_BUILD_TYPE=Release \
      ..
make -j$(nproc)

Available toolchain files in platforms/linux/:

• arm-gnueabi.toolchain.cmake - ARM v7 with hard float
• aarch64-gnu.toolchain.cmake - ARM 64-bit
• riscv64-gcc.toolchain.cmake - RISC-V 64-bit (GCC)
• riscv64-clang.toolchain.cmake - RISC-V 64-bit (Clang)
• ppc64le-gnu.toolchain.cmake - PowerPC 64-bit little-endian
• mips64r6el-gnu.toolchain.cmake - MIPS 64-bit

Build Configuration Options

Common CMake Options

cmake -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=/usr/local \
      -DBUILD_EXAMPLES=ON \
      -DBUILD_TESTS=OFF \
      -DBUILD_PERF_TESTS=OFF \
      -DWITH_OPENGL=ON \
      -DWITH_TBB=ON \
      -DWITH_GTK=ON \
      ..

Minimal Build for Embedded Systems

cmake -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DBUILD_SHARED_LIBS=OFF \
      -DBUILD_TESTS=OFF \
      -DBUILD_PERF_TESTS=OFF \
      -DBUILD_EXAMPLES=OFF \
      -DWITH_GTK=OFF \
      -DWITH_QT=OFF \
      -DWITH_OPENGL=OFF \
      -DWITH_FFMPEG=OFF \
      ..

GPU Acceleration

CUDA (NVIDIA)

# Install CUDA Toolkit from NVIDIA
# https://developer.nvidia.com/cuda-downloads

cmake -DWITH_CUDA=ON \
      -DCUDA_ARCH_BIN="6.0 6.1 7.0 7.5 8.0 8.6" \
      -DCMAKE_BUILD_TYPE=Release \
      ..

OpenCL

# Install OpenCL headers and ICD loader
sudo apt install opencl-headers ocl-icd-opencl-dev

cmake -DWITH_OPENCL=ON \
      -DCMAKE_BUILD_TYPE=Release \
      ..

VA-API (Intel)

# Install VA-API development files
sudo apt install libva-dev

cmake -DWITH_VA=ON \
      -DCMAKE_BUILD_TYPE=Release \
      ..

Installation

System-Wide Installation

System-wide installation requires root privileges and may conflict with distribution packages. Consider using a custom prefix instead.

# Default installation to /usr/local
sudo make install
sudo ldconfig

# Files are installed to:
# /usr/local/lib - libraries (.so files)
# /usr/local/include/opencv4 - headers
# /usr/local/bin - executables
# /usr/local/share/opencv4 - data files
# /usr/local/lib/cmake/opencv4 - CMake config

Custom Installation Directory

# Install to user directory
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local \
      -DCMAKE_BUILD_TYPE=Release \
      ..
make -j$(nproc)
make install

# Update library path
echo 'export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

Verification

Verify your OpenCV installation:

1. Check Installed Files

   # Check libraries
   ls build/lib/
   
   # Check CMake package
   ls build/opencv*.cmake
   
2. Test with Python

   python3 -c "import cv2; print(cv2.__version__)"
   
3. Build Info

   python3 -c "import cv2; print(cv2.getBuildInformation())"
   

Distribution-Specific Notes

Ubuntu/Debian

# Install from distribution packages (older version)
sudo apt install libopencv-dev python3-opencv

# Or build from source for latest version
sudo apt install build-essential cmake git pkg-config \
                 libgtk-3-dev libavcodec-dev libavformat-dev \
                 libswscale-dev

Fedora/RHEL

# Install from distribution packages
sudo dnf install opencv opencv-devel

# Or build from source
sudo dnf install gcc gcc-c++ cmake git gtk3-devel \
                 ffmpeg-devel python3-devel numpy

Arch Linux

# Install from distribution packages
sudo pacman -S opencv vtk hdf5 glew

# Or build from source
sudo pacman -S base-devel cmake git gtk3 ffmpeg python-numpy

Troubleshooting

CMake cannot find dependencies

Install development packages for missing dependencies:

# Check CMake output for missing packages
# Install corresponding -dev or -devel packages
sudo apt install lib<package>-dev

Linking errors during compilation

Clean and rebuild:

rm -rf build/
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

Python module not found after installation

Ensure Python can find the cv2 module:

# Find where cv2.so was installed
find /usr/local -name "cv2*.so"

# Add to Python path if needed
export PYTHONPATH=/usr/local/lib/python3.x/site-packages:$PYTHONPATH

Next Steps

CMake Configuration

Explore all CMake configuration options

Getting Started

Write your first OpenCV application

Cross-Compilation

Build for embedded systems

GPU Acceleration

Enable CUDA and OpenCL support