Install OpenCV on Raspberry Pi
Last updated: August 10, 2023
This comprehensive guide explains how to install OpenCV on an Raspberry Pi with an 32-bit operating system.
If you have a 64-bit operating system, please follow the 64-bit OpenCV guide.
Various installation methods will be described, from very simple to extensive. We will discuss the similarities and differences.
We would like to thank David Booth for providing us with a better version check!
Run the command getconf LONG_BIT and verify your version with the screen dump below.
Looking for a smaller OpenCV footprint? Our OpenCV Lite installation might be just what you needed. Only the very basics installed, saving you a lot of memory.
Over the years we have published more guides about OpenCV. They can be found in the archives.
On June 28, 2023, OpenCV released version 4.8.0. As usual, most of the changes and improvements can be found in the DNN module, apart from the bug fixes. One nice improvement is the TFLite models support, including int8 quantized models. Also interesting are the improvements made for ARMv8 cores. Now deep learning models will run even faster on the Raspberry Pi. More info can be found in the change log.
On December 17, 2022, OpenCV released version 4.7.0. As usual, most of the changes and improvements can be found in the DNN module, apart from the bug fixes. More info in the change log.
On June 7, 2022, OpenCV released version 4.6.0. As usual, most of the changes and improvements can be found in the DNN module, apart from the bug fixes. Also noteworthy is the support for FFmpeg 5.0. More info in the change log.
We have to live with the extra line -D PYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages.
As of Python 3.12, the installation in the dist-packages folder is deprecated in favour of the site-package folder.
Method 1: Pip.
Basically, there are three ways to install OpenCV on a machine.
Very important, do not mix the methods. They will interfere and cause crashes. If you want to switch, please uninstall the previous installation before continuing.
Now let's take a closer look and, more importantly, their differences.
First, we have the Python package manager pip. If you are only programming in Python, you can use this method.
It will install OpenCV only for Python, not C++.
# only Python
$ pip3 install opencv-contrib-python
Sometimes you see $ pip3 install opencv-python. The above-given command will install this package also.
The maintainers of the pip repository are pretty up-to-date. Mostly you get the latest version of OpenCV.
Method 2: sudo apt-get install.
You can use the apt-get installation if you want the C++ version of OpenCV.
In addition, if you want to use Python bindings, you need the second command also.
# only C++
$ sudo apt-get install libopencv-dev
# need Python also?
$ sudo apt-get install python3-opencv
This time the repository is not up to date. At the time of writing, version 4.8.0 has just been released, while version 4.5.1, dated December 2020 (!), has been installed. You are missing many improvements and bug fixes.
Using the apt-get install method, OpenCV may be upgraded when you use $ sudo apt-get upgrade. It sounds fine, but it can have unforeseen consequences. Software, like Pytorch, or TensorFlow, depends on the OpenCV version found during their installation on your Raspberry Pi. Upgrading to a newer version can cause a package to complain (you're lucky) or to stop functioning (too bad).
One of the solutions here is using a virtual environment. You will find detailed information about the virtual environment at the end of this manual. Install your environment first. Then you can install OpenCV inside it.
Note that the installation puts all headers files in the /usr/include/opencv4 directory, whereas we use the /usr/local/include/opencv4 folder throughout our GitHub repos.
Method 3: compiling the source.
In fact, the best method to install OpenCV on your Raspberry Pi is to compile the source code. You always have the latest version while controlling all the features you want to add. The method generates the C++ libraries and the Python bindings. You have them all in one. It sounds complicated, but if you follow the instructions, it's not that hard.
Before we can start the actual build, the memory swap space needs to be enlarged. For daily use a swap memory of 100 Mbyte is sufficient. However, with the massive build ahead of use, extra memory space is crucial. Enlarge the swap space with the following command. OpenCV requires at least a total of 5.8 GB of memory.
This command opens Nano, a very lightweight text editor, with the system file /sbin/phys-swapfile. With the arrow keys, you can move the cursor to the CONF_MAXSWAP line where the new value 4096 can be entered. Next, close the session with the <Ctrl+X> key combination. With <Y> and <Enter> changes are being saved. With the same procedure, you can alter the CONF_SWAPSIZE in the /etc/dphys-swapfile.
The slide show clarifies the procedure.
# enlarge the boundary (CONF_MAXSWAP)
$ sudo nano /sbin/dphys-swapfile
# give the required memory size (CONF_SWAPSIZE)
$ sudo nano /etc/dphys-swapfile
# reboot afterwards
$ sudo reboot
If your Raspberry Pi has only 1 GByte of RAM, obviously, you have to increase the swap space not with 4096, but with 5120. The same applies to the 4 GByte version; a 2048 GB swap space is now sufficient. In that case, you don't have to alter the CONF_MAXSWAP in /sbin/dphys-swapfile.
We restore the swap space to its original size after the installation; there is no need to wear your SD card unnecessarily.
As explained here, the physical RAM chip is used both by the CPU and the GPU. Check and change the amount to at least 128 Mbyte if necessary, using the following menu.
Installing OpenCV on your Raspberry Pi is not that complicated. With its 60 command lines, it's more of an administrative task. That's why we've created an installation script that executes all the commands in this guide in one go. Use it if you want. It shouldn't cause any problems. The entire installation will take an hour and a half. Make sure you have enough swap space (5.8 GB) before running the script.
If you want to beautify your OpenCV with the Qt5 GUI, follow the instructions on the GitHub page, or in the section below.
Cleaning and lowering dphys-swap should now be done manually according to these instructions.
Not using the script? Here's the full guide.
The OpenCV software uses other third party software libraries. These must be installed first. Some come with the Raspberry 64-bit operating system, others may already be installed. Better to be safe than sorry so here's the full list. Only the latest packages are installed according to the procedure.
# check for updates
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install build-essential cmake git unzip pkg-config
$ sudo apt-get install libjpeg-dev libpng-dev
$ sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev
$ sudo apt-get install libgtk2.0-dev libcanberra-gtk* libgtk-3-dev
$ sudo apt-get install libgstreamer1.0-dev gstreamer1.0-gtk3
$ sudo apt-get install libgstreamer-plugins-base1.0-dev gstreamer1.0-gl
$ sudo apt-get install libxvidcore-dev libx264-dev
$ sudo apt-get install python3-dev python3-numpy python3-pip
$ sudo apt-get install libtbb2 libtbb-dev libdc1394-22-dev
$ sudo apt-get install libv4l-dev v4l-utils
$ sudo apt-get install libopenblas-dev libatlas-base-dev libblas-dev
$ sudo apt-get install liblapack-dev gfortran libhdf5-dev
$ sudo apt-get install libprotobuf-dev libgoogle-glog-dev libgflags-dev
$ sudo apt-get install protobuf-compiler
Qt is an open-source toolkit for the development of cross-platform graphical user interfaces. It also works on the Raspberry Pi. The software can be used to beautify OpenCV windows and other user interfaces, such as sliders and checkboxes. It is absolutely not mandatory for the working of OpenCV, only to embellish the look. Must be said, that using Qt5 will slow down your OpenCV by a few percent. If you go for the fastest possible apps, don't use it.
If you want the Qt5 support enabled in OpenCV, you have to download the library as shown in the command below. The next step is to set the -D WITH_QT flag during the build.
# only install if you want Qt5
# to beautify your OpenCV GUI
$ sudo apt-get install qt5-default
When all third-party software is installed, OpenCV itself can be downloaded. There are two packages needed; the basic version and the additional contributions. After downloading, you can unzip the files. Please be aware of line wrapping in the text boxes. The two commands are starting with wget and ending with zip.
Now it is time to decide whether or not to use a virtual environment for your OpenCV installation. We don't use the virtual environment. Instead, we simply swap the SD-card if needed. However, feel free to install a virtual environment. All instructions are given in the virtual environment section at the end of this guide.
Before we begin with the actual build of the library, there is one small step to go. You have to make a directory where all the build files can be located.
$ cd ~/opencv
$ mkdir build
$ cd build
Now it is time for an important step. Here you tell CMake what, where and how to make OpenCV on your Raspberry. There are many flags involved. The most you will recognize. You will probably notice the -D WITH_QT=OFF line. Here Qt5 support is disabled. Set -D WITH_QT=ON if you choose to use the Qt5 software for the GUI. We save space by excluding any (Python) examples or tests.
There are only bare spaces before the -D flags, not tabs. By the way, the two last dots are no typo. It tells CMake where it can find its CMakeLists.txt (the large recipe file); one directory up.