Install OpenCV 4.5 on Raspberry Pi 4
Last updated: December 31, 2021
This article helps you install OpenCV 4.5.x on Raspberry Pi 4 with a 32-bit operation system.
Although written for the Raspberry Pi 4, the guide can also be used without any change for the Raspberry 3 or 2.
You can find the release notes of version 4.5.0 on the GitHub page of OpenCV here.
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.
On December 22, 2020, OpenCV released version 4.5.1. The most important improvement in this version is the work on the G-API framework and the RISC-V port. Neither will affect the Raspberry Pi. That's why we do not have a special installation guide for this version. Feel free to change the version numbers from 4.5.0 to 4.5.1 during downloading, if you prefer to use this version over 4.5.0.
On April 2, 2021, OpenCV released version 4.5.2. Find the significant changes in version in the log file here. Important changes are made in the imgproc, videoio and DNN module. Feel free to change the version numbers from 4.5.0 to 4.5.2 during downloading.
On July 5, 2021, OpenCV released version 4.5.3. Besides various bug fixes and improvements, the most significant changes are the DaSiamRPN tracker, a GPU FFmpeg backend for videoio and MatMul support in the CUDA backend. More info here.
On October 11, 2021, OpenCV released version 4.5.4. The main change is the continuous improvements of the DNN module. Of course there are bug fixes and improvements. More info here.
On Decemeber 25, 2021, OpenCV released version 4.5.5. Again the larges changes are improvements of the DNN module. Of course there are bug fixes and improvements. More info here.
There is one problem you should know. The Python3 installation script is incorrectly modified. It will put all libraries in the wrong directory and Python will not find them. By adding -D PYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages to the build, the libraries are stored in the correct folder. We will remove this workaround once the issue is resolved. Here is the bug report on GitHub.
Use a fast SD memory card for your Raspberry Pi 4. 100MB/s and a capacity of 32 GB is perfect.
The operating system is installed by the new Raspberry Pi Image Tool from this site. The Image Tool can write an operating system of your choice on an SD card. At the same time, it will format the card into the correct ext4 for the Raspberry Pi, even a 64, 128 or even 256 GByte card. Different image formats are supported, making this tool a better alternative to balena Etcher.
The second step is downloading the OS of your choice for your Raspberry Pi 4. The slideshow below shows how easy the whole image writing process is. After successful installing the Raspbian operating system, it is time to update and upgrade your operating system with the next commands in the terminal.
As explained here, the physical RAM chip is used both by the CPU and the GPU. On a Raspberry Pi 2 or 3 default is 64 Mbyte allocated for the GPU. The Raspberry Pi 4 has a 76 Mbyte GPU memory size. It can be somewhat small for vision projects, better to change this now to a 128 Mbyte. To increase the amount of memory for the GPU, use the following menu. After this action, the system wants to reboot. Let's do that.
With a fresh and clean Raspbian operating system, the last check is the EEPROM software version. The Raspberry Pi 3 had all the operating software on the SD card. The Raspberry Pi 4, on the other hand, is also partially booted from two EEPROMs. These EEPROMs are programmed after PCB assembly in the factory. The Raspberry Pi foundation has recently released new and improved software for these EEPROMs. This nothing to do with OpenCV, but all the more with heat dissipation. In one of our vision applications, the heat of the CPU drops from 65 °C (149 °F) to 48 °C (118 °F) simply by updating the EEPROMs contents. And, as you know, a low CPU temperature will prolong your Pi lifespan. For more information see this article.
Check, and if needed update, the EEPROMs with the following commands. The screen dumps speak for there self.
# to get the current status
$ sudo rpi-eeprom-update
# if needed, to update the firmware
$ sudo rpi-eeprom-update -a
$ sudo reboot
Some words of warning. Do not use pip to install OpenCV on your Raspberry Pi. First of all, pip installations don't support C++ due to missing header files. If you want to write code in C++, as we like to do, never use pip. Secondly, at the time of writing (Oct 2020), the OpenCV 4.1.1 version will be installed by pip. This version depends on an atomic library. Although available, the Raspbian operation system will only use this library when forced to do so. This can be done by the LD_PRELOAD trick. Not a convenient way to have this explicit dependency. And as of last, with NOOBS 3.1.1, you will be dragged into missing dependencies like libQTtest etc.
The same story applies to sudo apt-get install python3-opencv. The installed version of OpenCV (3.2.0 at the moment) neither supports C++. Another possible pitfall may be the repository. As soon as this ecosystem is updated with a newer version, a simple command like sudo apt-get upgrade will automatically install version 4.0.0 or higher which is incompatible with the 3 series. Unless you have isolated your OpenCV in a virtual environment, you are facing some time-consuming repair work on your old projects. On top of this all, and even worse, the installed version is not optimized for the NEON-ARM cores of the Raspberry Pi. So you end up with a library that could be much faster if it was installed manually according to the procedure below.
The sudo apt-get install libopencv-dev installation is another not so good idea. It generates a set of files suitable for C ++ coding. However, this OpenCV package is not recognized by Python. The installed version is again the old-fashioned 3.2.0. At the risk that once the ecosystem is updated, a sudo apt-get upgrade command will replace it for the incompatible 4.0.0 version.
Before you install OpenCV on your Raspberry Pi 4, it is time for a final version check. Many readers just jump into the guide, skipping the introduction, often because they have already an operating system working. For those, please give the command uname -a and check your version.
Do you have the 32-bit version, armv7l, please continue. If your version is the 64 bit, aarch64, you can follow the instructions on this page.
Curious about the Raspberry 64 bit operating system? Check this page to see if an upgrade may be an idea.
The next step is to increase your swap space. OpenCV needs a lot of memory to compile. The latest versions want to see a minimum of 6.5 GB of memory before building. Your swap space is limited to 2048 MByte by default. To exceed this 2048 MByte limit, you will need to increase this maximum in the /sbin/dphys-swapfile. Everything is demonstrated in the slideshow below.
# edit the swap configuration
$ sudo nano /sbin/dphys-swapfile
$ sudo nano /etc/dphys-swapfile
$ sudo reboot
Installing OpenCV on your Raspberry Pi is not that complicated. With its 60 command lines, it is more of an administrative task. That's why we created an installation script that executes all commands in this guide at once. Use it if you want, it shouldn't cause any problems. The whole installation will take one and a half hour to complete. It starts with the installation of the dependencies and ends with the ldconfig.
If you want to beautify your OpenCV with the Qt5 GUI, follow the instructions on the GitHub page, or in the section below.
Not using the script? Here's the full guide.
The OpenCV software uses other third-party software libraries. These have to be installed first. Some come with the Raspbian operating system, others may have been gathered over time, but it's better to be safe than sorry, so here is the complete list. Only the latest packages are installed by the procedure.
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install cmake gfortran
$ sudo apt-get install python3-dev python3-numpy
$ sudo apt-get install libjpeg-dev libtiff-dev libgif-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 libavcodec-dev libavformat-dev libswscale-dev
$ sudo apt-get install libgtk2.0-dev libcanberra-gtk*
$ sudo apt-get install libxvidcore-dev libx264-dev libgtk-3-dev
$ sudo apt-get install libtbb2 libtbb-dev libdc1394-22-dev libv4l-dev
$ sudo apt-get install libopenblas-dev libatlas-base-dev libblas-dev
$ sudo apt-get install libjasper-dev liblapack-dev libhdf5-dev
$ sudo apt-get install protobuf-compiler
# The latest Debian 11, Bullseye, dropped the support on python2
# don't install python-dev and python-numpy on a Bullseye OS
# only if you have a Debian 10, Buster OS
$ sudo apt-get install python-dev python-numpy
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. Check before downloading the latest version at https://opencv.org/releases/. If necessary, change the names of the zip files according to the latest version. 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. One of the main reasons for applying virtual environments is to protect your projects against incompatibility between package versions. Suppose you have OpenCV 2.4.13 and OpenCV 4.5.0 installed on your Raspberry Pi and you give the command >> import cv2 in Python 3. Which version will Python take? Placing the versions in separate environments is the solution to this problem. Now you can activate one environment with the command workon cv2413, do something with the OpenCV 2.4.13 library, leave environment with deactivate, and enter the OpenCV 4.5.0 environment with workon cv450 for instance.
If you stick to one OpenCV version, as many people do, there is no need for a virtual environment. Neither if you program in C++. In this language you must explicitly tell the compiler where the OpenCV folders with the headers and libraries are located. Obvious, you have installed your versions in unique locations. By the way, a bare OpenCV takes up about 1 Gbyte of space on your SD card.
Another way of dealing with versions is by using different micro-SD cards, each with a complete Raspbian OS and a different OpenCV version. Now you don't have different virtual environments, but separate hardware environments. The price of those micro-SD cards is nowadays certainly no obstacle.
Install a virtual environment.
Step one is some administration. We only use Python 3 because the support of Python 2.7 has stopped at the beginning of 2020. You have first to determine your Python 3 version and location. This location must be placed in the (hidden) ~/.bashrc file. The easiest way is a direct injection at the end of the file. You don't have to use an editor like nano or leafpad now.
# get version
$ python3 --version
# get location
$ which python 3.7
# merge VIRTUALENVWRAPPER_PYTHON=location/version
$ echo "export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3.7" >> ~/.bashrc
# reload profile
$ source ~/.bashrc
The Python location in the above commands was /usr/bin/python3.7. This location is passed as an argument in the echo command. The next step is installing the virtual environment software. This can be done with the following commands.
$ sudo pip3 install virtualenv
$ sudo pip3 install virtualenvwrapper
The last step is again some administration in the ~/.bashrc file, followed by a re-activation.
With the command mkvirtualenv, a virtual environment is set up for the OpenCV installation.
$ echo "export WORKON_HOME=$HOME/.virtualenvs" >> ~/.bashrc
$ echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
$ source ~/.bashrc
$ mkvirtualenv cv450
Your screen will be something like this.
There is only one dependency for Python with OpenCV in a virtual environment and that is Numpy. Although you have previously installed this package, you must also install it within the environment, otherwise, CMake cannot compile.
# without sudo!!!!
$ pip3 install numpy
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.
Recently there are some issues with Googles protobuf missing the link to the atomic library on the Raspberry Pi. When not found, it generates undefined symbol: __atomic_fetch_add_8 errors. An extra linker flag was introduced in the CMake build: OPENCV_EXTRA_EXE_LINKER_FLAGS=-latomic to overcome the problem. According to ticket #5219 the issue is now solved. That's why dropped the extra linker flag from our build. If you still facing problems with the atomic library, incorporate the line and rebuild OpenCV after removing the whole build folder first.