Building OpenCV on Linux

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:

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

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

Build OpenCV

Configure and compile:

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

Install

Install to system directories (optional):

sudo make install

Compiler Support

OpenCV supports multiple compilers on Linux:

GCC
Clang

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 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)
Ninja

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 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)
OpenCL
VA-API (Intel)

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

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

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

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

Check Installed Files

# Check libraries
ls build/lib/

# Check CMake package
ls build/opencv*.cmake

Test with Python

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

Build Info

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

Distribution-Specific Notes

Ubuntu/Debian
Fedora/RHEL
Arch Linux

# 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

# 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

# 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

Getting Started

Core Concepts

Modules

Tutorials

Language Bindings

Platform Support

Building OpenCV on Linux

Quick Start

Compiler Support

Build System Options

Installing Dependencies

Required Dependencies

Optional Dependencies

Cross-Compilation

ARM 32-bit (ARMv7)

ARM 64-bit (AArch64)

RISC-V 64-bit

Build Configuration Options

Common CMake Options

Minimal Build for Embedded Systems

GPU Acceleration

Installation

System-Wide Installation

Custom Installation Directory

Verification

Distribution-Specific Notes

Troubleshooting

Next Steps

CMake Configuration

Getting Started

Cross-Compilation

GPU Acceleration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Tutorials

Language Bindings

Platform Support

​Quick Start

​Compiler Support

​Build System Options

​Installing Dependencies

​Required Dependencies

​Optional Dependencies

​Cross-Compilation

​ARM 32-bit (ARMv7)

​ARM 64-bit (AArch64)

​RISC-V 64-bit

​Build Configuration Options

​Common CMake Options

​Minimal Build for Embedded Systems

​GPU Acceleration

​Installation

​System-Wide Installation

​Custom Installation Directory

​Verification

​Distribution-Specific Notes

​Troubleshooting

​Next Steps

CMake Configuration

Getting Started

Cross-Compilation

GPU Acceleration

Build docs developers (and LLMs) love

Quick Start

Compiler Support

Build System Options

Installing Dependencies

Required Dependencies

Optional Dependencies

Cross-Compilation

ARM 32-bit (ARMv7)

ARM 64-bit (AArch64)

RISC-V 64-bit

Build Configuration Options

Common CMake Options

Minimal Build for Embedded Systems

GPU Acceleration

Installation

System-Wide Installation

Custom Installation Directory

Verification

Distribution-Specific Notes

Troubleshooting

Next Steps