Installing OpenCV on the Raspberry Pi

by Emmet

Updated Sep 30, 2022

Throughout this guide, we will walk you through the process of setting up OpenCV on your Raspberry Pi.

Successfully installing OpenCV to your Raspberry Pi requires a couple of different steps and a fair bit of patience.

For those who do not know what OpenCV is. It is a library of different programming functions that are aimed at dealing with real-time computer vision.

Using computer vision, you can interpret images and videos in real-time. Allowing you to perform tasks such as motion detection and facial recognition with relative ease.

The Raspberry Pi is an excellent platform for starting to learn OpenCV and also doubles as an affordable and small device.

Equipment List

Here is all the equipment that we recommend for this Raspberry Pi OpenCV tutorial.

Optional

This tutorial was tested using the latest version of Raspbian Buster. If you are running an older version of Raspbian, you can use our guide to upgrade to Buster.

Installing Packages for OpenCV

In this section, we will be walking you through the process of installing all the packages you need to compile and run the OpenCV software.

As OpenCV requires so many packages on the Raspberry Pi, we will install these over a couple of steps.

1. Before proceeding, we should first update any preexisting packages.

You can update the currently installed packages by running the following two commands.

sudo apt update
sudo apt upgrade

2. Now we can start the process of installing all the packages we need for OpenCV to compile.

To start, run the command below. This command will install the packages that contain the tools needed to compile the OpenCV code.

sudo apt install cmake build-essential pkg-config git

3. Next, we are going to install the packages that will add support for different image and video formats to OpenCV.

Install these libraries to your Raspberry Pi with the following command.

sudo apt install libjpeg-dev libtiff-dev libjasper-dev libpng-dev libwebp-dev libopenexr-dev
sudo apt install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libdc1394-22-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev

4. Our next step is to install all the packages needed for OpenCV’s interface by using the command below.

sudo apt install libgtk-3-dev libqt5gui5 libqt5webkit5 libqt5test5 python3-pyqt5

5. These next packages are crucial for OpenCV to run at a decent speed on the Raspberry Pi.

You can install these packages by running the following command.

sudo apt install libatlas-base-dev liblapacke-dev gfortran

6. The second last lot of packages thaat we need to install relate to the Hierarchical Data Format (HDF5) that OpenCV uses to manage data.

Install the HDF5 packages to your Pi by using the command below.

sudo apt install libhdf5-dev libhdf5-103

7. Finally, we can install the final few packages by using the command below.

These last few packages will allow us to compile OpenCV with support for Python on our Raspberry Pi.

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

Before proceeding to the next section, make sure all the packages installed successfully.

Preparing your Raspberry Pi for Compiling OpenCV

1. With all the required packages to compile OpenCV on our Raspberry Pi now installed, we need to do some preparatory work before we can start the compilation process.

We will now need to temporarily increase the size of the swap space to help the process of compiling OpenCV on the Raspberry Pi.

The swap space is used by the operating system when the device has run out of physical RAM. While swap memory is a lot slower than RAM, it can still be helpful in certain situations.

Begin modifying the swap file configuration by running the following command.

sudo nano /etc/dphys-swapfile

2. While we are within this file, we need to find and replace the following line.

Find

CONF_SWAPSIZE=100

Replace With

CONF_SWAPSIZE=2048

Once changed, save the file by pressing CTRL+X followed by Y then Enter.

3. As we have made changes to the swapfile configuration, we need to restart its service by utilizing the command below.

sudo systemctl restart dphys-swapfile

By restarting the service, we are forcing it to recreate the swap file.

4. Next, let’s go ahead and clone the two OpenCV repositories we need to our Raspberry Pi.

Running these two commands will retrieve the latest available version of OpenCV from their git repository.

git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

As these repositories are quite large, they may take some time to clone to your Raspberry Pi.

Compiling OpenCV on your Raspberry Pi

1. Let’s start by creating a directory called “build” within the cloned “opencv” folder and then changing the working directory to it.

mkdir ~/opencv/build
cd ~/opencv/build

In this folder, we will be compiling OpenCV on your Raspberry Pi.

2. Now that we are within our newly created build folder, we can now use cmake to prepare OpenCV for compilation on our Raspberry Pi.

Run the following command to generate the required makefile.

cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
    -D ENABLE_NEON=ON \
    -D ENABLE_VFPV3=ON \
    -D BUILD_TESTS=OFF \
    -D INSTALL_PYTHON_EXAMPLES=OFF \
    -D OPENCV_ENABLE_NONFREE=ON \
    -D CMAKE_SHARED_LINKER_FLAGS=-latomic \
    -D OPENCV_PYTHON_INSTALL_PATH=lib/python3.9/dist-packages \
    -D BUILD_EXAMPLES=OFF ..

3. Once the make file has successfully finished generating, we can now finally move on to compiling OpenCV by running the command below.

We use the argument -j$(nproc) to tell the compiler to run a compiler for each of the available processors.

Doing this will significantly speed up the compilation process and allow each core on the Raspberry Pi to work on compiling OpenCV.

make -j$(nproc)

Please note that the compilation process can take considerable time. On our Raspberry Pi 4, this process took about 1 hour to complete.

If the compilation process is for some reason failing to complete or appearing to get hung, there is a chance the CPU is getting locked up.

To get around this, you can try running a single make process. This should reduce the likely hood of issues but cause longer compilation times.

make

4. When the compilation process finishes, we can then move on to installing OpenCV.

Luckily for us, this is a reasonably straightforward process and requires you to run the following command.

sudo make install

This command will copy all the required files into there needed locations automatically.

5. Now we also need to regenerate the operating systems library link cache.

The Raspberry Pi won’t be able to find our OpenCV installation if we don’t run the following command.

sudo ldconfig

Cleaning up after Compilation

1. Now that we have finished compiling OpenCV, we no longer need to have such a large swap file.

Let’s again edit the swap file configuration by using the following command.

sudo nano /etc/dphys-swapfile

2. Within this file, you need to find and change the following line.

Find

CONF_SWAPSIZE=2048

Replace With

CONF_SWAPSIZE=100

When done, save the file by pressing CTRL+X followed by Y then Enter.

3. Now our final cleanup task requires us to restart the swap file service.

Restarting the service will downsize the file from 2GB to 100 MB.

sudo systemctl restart dphys-swapfile

Testing OpenCV on your Raspberry Pi

1. To test whether OpenCV is now installed to our Raspberry Pi, we will make use of our Python 3 installation.

Launch into the Python terminal by running the command below.

python3

2. While we are within Python, we can now import the OpenCV Python module using the command below.

By importing the module, we can first check to see if OpenCV will even load on our Pi.

import cv2

3. With the OpenCV module now imported, we should be able to retrieve its version.

To retrieve OpenCV’s version, use the following command.

cv2.__version__

4. If everything is now working as intended and OpenCV has been successfully installed to your Raspberry Pi, you should see text like the following appear in the command line.

'4.6.0'

Hopefully, at this point you will now have OpenCV up and running.

If you have run into any issues or have any feedback on this Raspberry Pi OpenCV tutorial, then feel free to drop a comment below.

50 Comments

Eren on October 3, 2022 at 3:12 pm

i’m using Linux XFCE and ras version is “Rasperry4 Model B”

Reply
1. Emmet on October 3, 2022 at 4:21 pm
  
  Editor
  Hi Eren,
  
  Ok, all I need to know now is the version of Python 3 that is installed on your system to see if it’s something that can easily be remedied within the tutorial. You can get the full version string by using the following command.
  
  python3 --version
  
  Cheers,
  Emmet
Eren on October 3, 2022 at 4:48 am

Hi, i’m getting a wrong output when i write “cv2.__version__” in python . It says “3.2.0” how can i upgrade this to “4.6.0” ?

Reply
1. Emmet on October 3, 2022 at 1:13 pm
  
  Editor
  Hi Eren,
  
  That is strange, you should definitely end up with the latest version after running through this tutorial.
  
  What version of Raspberry Pi OS are you running? Or what OS are you running in general.
  
  Additionally, what version of Python do you have installed to your Pi. You can get this version by using the following in the command line.
  
  python3 --version
  
  Cheers,
  Emmet
Emil on September 30, 2022 at 7:43 am

Hi,
I had the same problem as Barry and i just did step 6-8 in the “Compiling OpenCV on your Raspberry Pi“ section but i still get “No module named cv2”.

Please help?

Reply
1. Emmet on September 30, 2022 at 9:37 pm
  
  Editor
  Hi Emil,
  
  I have removed those steps since they don’t seem to of been an actual fix for the issue that is occurring. I haven’t managed to replicate the failure to import locally either.
  
  Could you please try restarting your Raspberry Pi and see if that fixes your issues.
  
  You can reboot by using the following command.
  
  sudo reboot
  
  Cheers,
  Emmet
2. Emil Lilleslåtten on September 30, 2022 at 9:47 pm
  
  Hi Emmet.
  Did it, still dont work.
  
  Maybe i should try the whole tutorial over again? Is it a easy command to completely delete my installation?
3. Emmet on September 30, 2022 at 11:06 pm
  
  Editor
  Hi Emil,
  
  Ok, I have tried something else so hopefully this will fix the issues. This time I adjusted the cmake options so that it will force the install directory for OpenCV’s python package into the “dist-packages” directory rather than “site-packages”.
  
  To clear up from the previous install, use the following commands then start again from the “Compiling OpenCV on your Raspberry Pi” section. This isn’t a perfect clear but should at least remove the Python package that doesn’t seem to be getting picked up anyway.
  
  sudo rm -rf ~/opencv/build sudo rm -rf /usr/local/lib/python3.9/site-packages/cv2
  
  Please let me know how you get on with the latest changes.
  
  Cheers,
  Emmet
4. Emil on October 1, 2022 at 9:10 am
  
  Emmet!
  Tried it, everything works now, thank you so much for your time!
5. Emmet on October 1, 2022 at 2:05 pm
  
  Editor
  
  Hi Emil,
  
  Glad to hear that the workaround finally worked!
  
  Cheers,
  Emmet
Barry on September 29, 2022 at 8:34 am

This does not work on my raspberry pi zero 2 w. Error message: No module named cv2

Reply
1. Emmet on September 29, 2022 at 7:08 pm
  
  Editor
  
  Hi Barry,
  
  It looks like most issues with this seems to be related to the “site-packages” directory not being picked up by Python.
  
  In the “Compiling OpenCV on your Raspberry Pi” section can you please try following the newly added steps (Step 6 to 8). This should hopefully resolve the issues
  
  Please let me know if this fixes the problem.
  
  Cheers,
  Emmet
Airbutt on July 26, 2022 at 6:16 pm

What ever reason I had to append to sys.path also the site-packages folder

python3
>>>import sys
>>>sys.path.append(‘/usr/local/lib/python3.9/site-packages’)
>>>import cv2
>>>cv2.__version__
‘4.6.0-dev’

EUREKA! Great Thanks
Compilation on Raspberry 3b+ with (with one core) took about 6 hrs (overnight)

Rgds

Airbutt

Reply
1. marzsman on September 27, 2022 at 5:21 pm
  
  I had this same issue, after 3 installs I tried your solution for the import and it worked!
  Thanks a lot!!!
2. Moriz on April 27, 2023 at 4:15 pm
  
  Had the same issue. This worked. Thanks alot

Hi! The tutorial was super helpful. Thank you for putting together. I’m not sure this is a simple fix but when I get to the steps to test CV in python, I get this error:

Python 3.9.2 (default, Mar 12 2021, 04:06:34) 
[GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import cv2
RuntimeError: module compiled against API version 0xf but this version of numpy is 0xd
Traceback (most recent call last):
  File "", line 1, in 
  File "/home/spookytime/.local/lib/python3.9/site-packages/cv2/__init__.py", line 8, in 
    from .cv2 import *
ImportError: numpy.core.multiarray failed to import

Can anyone help me troubleshoot this issue? Thanks!

Emmet on May 19, 2022 at 2:18 pm

Editor
Hi Meg,

Could you please try installing numpy by using the following command.
```
sudo pip install -U numpy
```
Please let me know if it solves your issues with using OpenCV.

Cheers,
Emmet

Enda McNabola on February 23, 2022 at 10:25 am

Would it work on a Raspberry Pi 3B+ running on Python 3.7 or 3.9?

Reply
1. Emmet on February 23, 2022 at 11:47 pm
  
  Editor
  
  Hi Enda,
  
  Yes it definitely should. When I wrote this guide I tested it on a Raspberry Pi 3B+ and was running Python 3 at that time.
  
  Cheers,
  Emmet
Colin Walls on November 28, 2021 at 7:27 pm

Excellent tutorial. Worked for me on a Pi Zero and on a Pi 4

Reply
Joe on November 15, 2021 at 11:47 pm

Thanks for the well explained tutorial..

In step 4, the below three are not available.. Any work around or update ?
libqtgui4 libqtwebkit4 libqt4-test

Thanks in advance

Joe

Reply
1. Joe on November 16, 2021 at 12:37 am
  
  just an update.. I removed what was not not available and went ahead..
  It successfully go complied and for the first time in 3 days, I am getting a response to the import cv2 command..
  
  THANKS A LOT!!!!!!!!

HI! If you want this to work on the Pi zero, you will need to change the compilation options slightly, otherwise after install, it will fail at import with: “Illegal instruction”

these options work on Raspi Zero:

cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
    -D ENABLE_NEON=OFF \
    -D ENABLE_VFPV3=OFF \
    -D BUILD_TESTS=OFF \
    -D INSTALL_PYTHON_EXAMPLES=OFF \
    -D OPENCV_ENABLE_NONFREE=ON \
    -D CMAKE_SHARED_LINKER_FLAGS=-latomic \
    -D BUILD_EXAMPLES=OFF ..

Dung Le on October 17, 2021 at 1:21 pm

As I can see some people having issue with Opencv installation. Opencv was installed successfully on my Raspberry Pi 4 4Gb RAM with SD Card 64Gb.
Use the standard OS – Raspberry Pi OS (32-bit) as it has libjasper-dev .

Reply