How to Set Up OpenCV on Raspberry Pi 4

OpenCV can be built from source on a Raspberry Pi and then checked by importing cv2 with Python 3. This guide assumes a Raspberry Pi running Raspberry Pi OS and a terminal session with an internet connection. The build can take a long time and needs substantial free storage; the time and feasible build parallelism depend on the board, memory, and selected OpenCV modules.

Select a Raspberry Pi and operating system

The source procedure is intended for a Raspberry Pi 4 Model B, though Raspberry Pi models with compatible operating systems may also be able to build OpenCV. Raspberry Pi OS is the operating-system scope for the commands below. This is an explicit guide assumption, not a claim that a particular OS release or board configuration has been tested. An older or lower-memory board may take longer to compile, and available disk space can constrain the build.

Prepare Raspberry Pi OS

Open a terminal on the Pi and update the package index and installed packages with sudo apt update followed by sudo apt upgrade. Install the compiler and tools, including build-essential, cmake, git, pkg-config, python3-dev, and python3-numpy, using sudo apt install build-essential cmake git pkg-config python3-dev python3-numpy. Package names and availability can vary by Raspberry Pi OS release; resolve package-manager errors for the installed release before continuing. Keep enough free disk space for the source trees and generated build files.

The python3-dev package supplies Python development headers needed when configuring a Python binding. Use the same Python 3 installation and environment when building and verifying OpenCV. If you use a virtual environment, plan how the build will locate that environment’s interpreter and NumPy rather than assuming the system Python and virtual environment are interchangeable.

Build and install OpenCV from source

Choose an OpenCV release that is compatible with the installed operating system and Python environment. If you want extra modules, choose the matching release of opencv-contrib; its modules are separate from the main OpenCV repository. The two source trees must use matching release versions. See the related opencv-contrib guide for context on the extra modules.

The following are command-line steps for a Raspberry Pi OS terminal, not a self-contained program. Replace VERSION in each command with the same OpenCV release tag. Clone the matching source trees into the home directory with git clone --branch VERSION --depth 1 https://github.com/opencv/opencv.git ~/opencv-VERSION and, when extra modules are needed, git clone --branch VERSION --depth 1 https://github.com/opencv/opencv_contrib.git ~/opencv_contrib-VERSION. Create a build directory with mkdir -p ~/opencv-VERSION/build, then enter it with cd ~/opencv-VERSION/build.

Configure the build from that directory with cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local -D OPENCV_EXTRA_MODULES_PATH="$HOME/opencv_contrib-VERSION/modules" ... Use the matching contrib directory in that option; omit the option if you are not building contrib modules. These are configuration choices; available options depend on the selected release and system dependencies.

Build from the configured directory with make -j2, then install with sudo make install. Choose a smaller job count if the Pi runs short of memory; fewer parallel jobs usually take longer. The build and installation commands depend on downloaded source, a working compiler toolchain, and compatible dependencies, so they cannot be represented as an isolated runtime example here.

Verify OpenCV in Python

Run the check with the Python 3 environment used by the build. It imports the binding and displays the version reported by the installed module. The supplied run completed with exit code 0, but it reported that cv2 was unavailable in that runtime environment, so a successful OpenCV import was not demonstrated there. The version is specific to the installation.

import importlib.util

if importlib.util.find_spec("cv2") is None:
    print("cv2 is not available in this Python environment.")
else:
    import cv2
    print(cv2.__version__)

A successful import confirms that this interpreter can find the cv2 module. If Python reports that the module cannot be found, check that the build installed its Python binding and that the command uses the intended interpreter. A version string alone does not confirm that every optional module or camera device is available.

Troubleshoot common installation failures

If compilation stops while the Pi is under memory pressure, rerun the build with fewer jobs, for example make -j1 from the build directory. This can reduce concurrent resource use but increases build time and does not guarantee that every failure will be resolved. Check the first compiler or CMake error in the log, confirm that CMake points to the matching opencv_contrib modules directory, and make sure both source trees use the same release tag.

If import cv2 fails after installation, verify that python3 is the interpreter configured for the build, and inspect whether the installation placed the binding in a directory that interpreter searches. Installing NumPy into a different Python environment does not make it available to the interpreter used by the build.

Conclusion

A Raspberry Pi OS source build uses CMake to configure OpenCV, compiles it with a job count appropriate for the device, and installs the resulting libraries. Importing cv2 with the matching Python 3 environment is the practical check that the binding is available. Select compatible, matching OpenCV and opencv-contrib releases for the installed system; this guide does not establish a tested compatibility matrix or guarantee build success on every Raspberry Pi configuration.