Honestly, I love the Raspberry Pi for teaching computer vision — it is perhaps one of the best teaching tools to expose programmers, developers, and students to the world of computer vision.
It’s great for hobbyists and garage-room hackers, as you get to learn on a cheap, but super fun piece of hardware. It’s awesome for businesses and products as they can deploy computer vision algorithms on cost-affordable and reliable hardware. The Raspberry Pi is also certainly prevalent in research and academia. Given its lost-cost, we can now undertake large-scale, distributed computer vision research projects using a fleet of Raspberry Pis.
Given these benefits and applicability to a wide variety of domains, it’s perhaps comes as no surprise that my tutorial on installing OpenCV and Python on your Raspberry Pi 2 and B+ is still one of the most popular posts on the PyImageSearch blog.
But today, that’s going to change — because I think this blog post will over take its predecessor become the most popular article on the PyImageSearch blog.
You see, we’re going to take a step forward and learn how to install the (just released) OpenCV 3.0 library for both Python 2.7 and Python 3+ on your Raspberry Pi.
That’s right. By the end of this step-by-step guide you’ll have the brand new OpenCV 3.0 library installed on your Raspberry Pi 2, along with either Python 2.7+ or Python 3+ bindings. This is definitely an exciting tutorial — up until now only Python 2.7 was supported by OpenCV. But now given the OpenCV 3.0 release, we can finally utilize Python 3+ in our projects.
And as you have seen elsewhere on the PyImageSearch blog, being able to utilize OpenCV on the Raspberry Pi has lead to be really great projects, such as an automated home surveillance and security system using Python + OpenCV + Dropbox + a Raspberry Pi 2:
So if you’re interested in building awesome computer vision based projects like this, then follow along with me and we’ll have OpenCV 3.0 with Python bindings installed on your Raspberry Pi 2 in no time.
Install OpenCV 3.0 for both Python 2.7+ and Python 3+ on your Raspberry Pi 2
UPDATE: The tutorial you are reading now covers how to install OpenCV 3 with Python 2.7 and Python 3 bindings on Raspbian Wheezy. Raspbian Jessie has now replaced Raspbian Wheezy and if this is the first time you are reading this tutorial then in all likelihood you are using Raspbian Jessie. Please use the following updated guides to help you install OpenCV + Python on your Raspberry Pi.
- How to install OpenCV 3.0 on Raspbian Jessie.
- Install guide: Raspberry Pi 3 + Raspbian Jessie + OpenCV 3.
The rest of this blog post will detail how to install OpenCV 3.0 for both Python 2.7 and Python 3+ on your Raspberry Pi 2. These install instructions could also be used for the B+, but I highly recommend that you use the Pi 2 for running OpenCV applications — the added speed and memory makes the Pi 2 much more suitable for computer vision.
In order to keep this tutorial concise and organized, I have broken down the OpenCV 3.0 install process into four sections:
- Section 1: Configuring your Raspberry Pi by installing the required packages and libraries. Regardless of whether you are using Python 2.7 or Python 3+, we need to take some steps in order to prepare our Raspberry Pi for OpenCV 3.0 — these steps are mainly calls to
apt-get
, followed by installing the required packages and libraries. - Section 2: Compiling OpenCV 3.0 with Python 2.7+ support. If you want to install OpenCV 3.0 with Python 2.7+ bindings on your Raspberry Pi, then this is the section that you’ll want to go to. After you complete this section, skip Section 3 and head right to Section 4.
- Section 3: Compiling OpenCV 3.0 with Python 3+ support. Similarly, if you want to install OpenCV 3.0 with Python 3+ bindings on your Pi 2, then complete Section 1 and skip right to Section 3.
- Section 4: Verifying your OpenCV 3.0 install. After you have installed OpenCV 3.0 with Python support on your Raspberry Pi 2, you’ll want to confirm that is is indeed installed correctly and working as expected. This section will show you how to verify your OpenCV 3.0 install and ensure it’s working correctly.
Python 2.7+ or Python 3+?
Before we get started, take a second and consider which version of Python you are going to use. Are you going to compile OpenCV 3.0 with Python 2.7 bindings? Or are you going to compile OpenCV 3.0 Python 3 bindings?
There are pros and cons of each, but the choice is honestly up to you. If you use Python 3 regularly and are comfortable with it, then go ahead and compile with Python 3 bindings. However, if you do a lot of scientific Python development, you might want to stick with Python 2.7 (for the time being at least). While packages such as NumPy, Scipy, and scikit-learn are certainly increasing the Python 3+ adoption rate in the scientific community, there are still many scientific packages that still require Python 2.7 — because of this, you can easily pigeonhole yourself if you go with Python 3 and then realize that many of the packages you use on a daily basis only support Python 2.7.
When in doubt, I normally suggest that scientific developers use Python 2.7 since it ensures capability with a larger set of scientific packages and allows you to run experiments with legacy code. However, that is quickly changing — so proceed with whichever Python version you are most comfortable with!
Section 1: Configuring your Raspberry Pi by installing required packages and libraries
Let’s kick off this OpenCV 3.0 install tutorial by updating our Raspberry Pi:
$ sudo apt-get update $ sudo apt-get upgrade $ sudo rpi-update
Timing: 9m 5s
Now we can install developer tools required to build OpenCV from source:
$ sudo apt-get install build-essential git cmake pkg-config
Timing: 43s
As well as install packages used to load various image formats from disk:
$ sudo apt-get install libjpeg8-dev libtiff4-dev libjasper-dev libpng12-dev
Timings: 27s
Let’s install some video I/O packages:
$ sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
Timings: 26s
Install GTK, which handles OpenCV’s GUI operations:
$ sudo apt-get install libgtk2.0-dev
Timings: 2m 20s
We can also optimize various functions (such as matrix operations) inside OpenCV by installing these packages:
$ sudo apt-get install libatlas-base-dev gfortran
Timings: 46s
At this point we have all our prerequisites installed, so let’s pull down the OpenCV repository from GitHub and checkout the 3.0.0
version:
$ cd ~ $ git clone https://github.com/Itseez/opencv.git $ cd opencv $ git checkout 3.0.0
Timings: 8m 34s
Update (3 January 2016): You can replace the 3.0.0
version with whatever the current release is (as of right now, it’s 3.1.0
). Be sure to check OpenCV.org for information on the latest release.
For the full, complete install of OpenCV 3.0, grab the opencv_contrib repo as well:
$ cd ~ $ git clone https://github.com/Itseez/opencv_contrib.git $ cd opencv_contrib $ git checkout 3.0.0
Timings: 1m 7s
Again, make sure that you checkout the same version for opencv_contrib
that you did for opencv
above, otherwise you could run into compilation errors.
Now we’re at at a crossroads, a sort of Choose Your Own (OpenCV) Adventure!
You can either follow Section 2 and compile OpenCV 3.0 with Python 2.7+ bindings. Or you can head to Section 3 and install OpenCV 3.0 with Python 3+ bindings. The choice is up to you — but choose wisely! Once you make the choice it will be non-trivial to change your mind later.
Note: It’s certainly possible to install OpenCV 3.0 for both versions of Python (it’s actually not too hard), but it’s outside the scope of this tutorial; I’ll be sure to cover this technique in a future post.
Section 2: Compiling OpenCV 3.0 with Python 2.7+ support
Install the Python 2.7 header files so we can compile the OpenCV 3.0 bindings:
$ sudo apt-get install python2.7-dev
Timings: 1m 20s
Install pip
, a Python package manager that is compatible with Python 2.7:
$ wget https://bootstrap.pypa.io/get-pip.py $ sudo python get-pip.py
Timings: 33s
Just as we did in the original tutorial on installing OpenCV 2.4.X on your Raspberry Pi, we are going to utilize virtualenv and virtualenvwrapper which allow us to create separate Python environments for each of our Python projects. Installing virtualenv
and virtualenvwrapper
is certainly not a requirement when installing OpenCV and Python bindings; however, it’s a standard Python development practice, one that I highly recommend, and the rest of this tutorial will assume you are using them!
Installing virtualenv
and virtualenvwrapper
is as simple as using the pip
command:
$ sudo pip install virtualenv virtualenvwrapper $ sudo rm -rf ~/.cache/pip
Timings: 17s
Next up, we need to update our ~/.profile
file by opening it up in your favorite editor and adding the following lines to the bottom of the file.
# virtualenv and virtualenvwrapper export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7 export WORKON_HOME=$HOME/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh
And if your ~/.profile
file does not exist, create it.
Now that your ~/.profile
file has been updated, you need to reload it so the changes take affect. To force a reload of the .profile
, you can: logout and log back in; close your terminal and open up a new one; or the most simple solution is to use the source
command:
$ source ~/.profile
Time to create the cv3
virtual environment where we’ll do our computer vision work:
$ mkvirtualenv cv3
Timings: 19s
If you ever need to access the cv3
virtual environment (such as after you logout or reboot your Pi), just source
your ~/.profile
file (to ensure it has been loaded) and use the
workon command:
$ workon cv3
And your shell will be updated to only use packages in the cv3
virtual environment.
Moving on, the only Python dependency we need is NumPy, so ensure that you are in the cv3
virtual environment and install NumPy:
$ pip install numpy
Timings 13m 47s
While unlikely, I have seen instances where the .cache
directory gives a “Permission denied” error since we used the sudo
command to install pip
. If that happens to you, just remove the .cache/pip
directory and re-install NumPy:
$ sudo rm -rf ~/.cache/pip/ $ pip install numpy
Awesome, we’re making progress! You should now have NumPy installed on your Raspberry Pi in the cv3
virtual environment, as shown below:
Note: Performing all these steps can be time consuming, so it’s perfectly normal to logout/reboot and come back later to finish the install. However, if you have logged out or rebooted your Pi then you will need to drop back into your cv3
virtual environment prior to moving on with this guide. If you do not, OpenCV 3.0 will not compile and install correctly and you’ll likely run into import errors.
So I’ll say this again, before you run any other command, you’ll want to ensure that you are in the cv3
virtual environment:
$ workon cv3
And once you are in cv3
virtual environment, you can use cmake
to setup the build:
$ cd ~/opencv $ mkdir build $ cd build $ cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D INSTALL_C_EXAMPLES=ON \ -D INSTALL_PYTHON_EXAMPLES=ON \ -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \ -D BUILD_EXAMPLES=ON ..
Update (3 January 2016): In order to build OpenCV 3.1.0
, you need to set -D INSTALL_C_EXAMPLES=OFF
(rather than ON
) in the cmake
command. There is a bug in the OpenCV v3.1.0 CMake build script that can cause errors if you leave this switch on. Once you set this switch to off, CMake should run without a problem.
CMake will run for about 30 seconds, and after it has completed (assuming there are no errors), you’ll want to inspect the output, especially the Python 2 section:
The key here is to ensure that CMake has picked up on the Python 2.7 interpreter and numpy
package associated with the cv3
virtual environment.
Secondly, be sure look at the packages path
configuration — this is the path to the directory where your OpenCV 3.0 bindings will be compiled and stored. From the output above, we can see that my OpenCV bindings will be stored in /usr/local/lib/python2.7/site-packages
All that’s left now is to compile OpenCV 3.0:
$ make -j4
Where the 4 corresponds to the 4 cores on our Raspberry Pi 2.
Timings: 65m 33s
Assuming OpenCV has compiled without an error, you can now install it on your Raspberry Pi:
$ sudo make install $ sudo ldconfig
At this point, OpenCV 3.0 has been installed on your Raspberry Pi 2 — there is just one more step to take.
Remember how I mentioned the packages path
above?
Take a second to investigate the contents of this directory, in my case /usr/local/lib/python2.7/site-packages/
:
You should see a file named cv2.so
, which is our actual Python bindings. The last step we need to take is sym-link the cv2.so
file into the site-packages
directory of our cv3
environment:
$ cd ~/.virtualenvs/cv3/lib/python2.7/site-packages/ $ ln -s /usr/local/lib/python2.7/site-packages/cv2.so cv2.so
And there you have it! You have just compiled and installed OpenCV 3.0 with Python 2.7 bindings on your Raspberry Pi!
Proceed to Section 4 to verify that your OpenCV 3.0 install is working correctly.
Section 3: Compiling OpenCV 3.0 with Python 3+ support
First up: Install the Python 3 header files so we can compile the OpenCV 3.0 bindings:
$ sudo apt-get install python3-dev
Timings: 54s
Install pip
, ensuring that it is compatible with Python 3 (note that I am executing python3
rather than just python
):
$ wget https://bootstrap.pypa.io/get-pip.py $ sudo python3 get-pip.py
Timings: 28s
Just like in the original tutorial on installing OpenCV 2.4.X on your Raspberry Pi 2, we are going to make use of virtualenv and virtualenvwrapper. Again, this is not a requirement to get OpenCV 3.0 installed on your system, but I highly recommend that you use these packages to manage your Python environments. Furthermore, the rest of this tutorial will assume you are using virtualenv
and virtualenvwrapper
.
Use the pip3
command to install virtualenv
and virtualenvwrapper
:
$ sudo pip3 install virtualenv virtualenvwrapper
Timings: 17s
Now that virtualenv
and virtualenvwrapper
are installed on our system, we need to update our ~/.profile
file that is loaded each time we launch a terminal. Open up your ~/.profile
file in your favorite text editor (if it doesn’t exist create it) and add in the following lines:
# virtualenv and virtualenvwrapper export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 export WORKON_HOME=$HOME/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh
In order to make the changes to our ~/.profile
file take affect, you can either (1) logout and log back in, (2) close your current terminal and open up a new one, or (3) simply use the source
command:
$ source ~/.profile
Let’s create our cv
virtual environment where OpenCV will be compiled and accessed from:
$ mkvirtualenv cv
Timings: 19s
Note: I gathered the Python 2.7+ and Python 3+ install instructions on the same Raspberry Pi so I could not use the same virtual environment name for each installation. In this case, the cv3
virtual environment refers to my Python 2.7 environment and the cv
virtual environment refers to my Python 3+ environment. You can name these environments whatever you wish, I simply wanted to offer a clarification and hopefully remove any confusion.
This command will create your cv
virtual environment which is entirely independent of the system Python install. If you ever need to access this virtual environment, just use the workon
command:
$ workon cv
And you’ll be dropped down into your cv
virtual environment.
Anyway, the only Python dependency we need is NumPy, so ensure that you are in the cv
virtual environment and install NumPy:
$ pip install numpy
Timings 13m 47s
If for some reason your .cache
directory is giving you a Permission denied error, just remove it and re-install NumPy, otherwise you can skip this step:
$ sudo rm -rf ~/.cache/pip/ $ pip install numpy
At this point you should have a nice clean install of NumPy, like this:
Alright, it’s taken awhile, but we are finally ready to compile OpenCV 3.0 with Python 3+ bindings on your Raspberry Pi.
It’s important to note that if you have logged out or rebooted, that you will need to drop back into your cv
virtual environment before compiling OpenCV 3.0. If you do not, OpenCV 3.0 will not compile and install correctly and you’ll be scratching your head in confusion when you try to import OpenCV and get the dreaded ImportError: No module named cv2
error.
So again, before you run any other command in this section, you’ll want to ensure that you are in the cv
virtual environment:
$ workon cv
After you are in the cv
virtual environment, we can setup our build:
$ cd ~/opencv $ mkdir build $ cd build $ cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D INSTALL_C_EXAMPLES=ON \ -D INSTALL_PYTHON_EXAMPLES=ON \ -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \ -D BUILD_EXAMPLES=ON ..
Update (3 January 2016): In order to build OpenCV 3.1.0
, you need to set -D INSTALL_C_EXAMPLES=OFF
(rather than ON
) in the cmake
command. There is a bug in the OpenCV v3.1.0 CMake build script that can cause errors if you leave this switch on. Once you set this switch to off, CMake should run without a problem.
After CMake has run, take a second to inspect the output of the make configuration, paying close attention to the Python 3 section:
Specifically, you’ll want to make sure that CMake has picked up your Python 3 interpreter!
Since we are compiling OpenCV 3.0 with Python 3 bindings, I’m going to examine the Python 3 section and ensure that my Interpreter
and numpy
paths point to my cv
virtual environment. And as you can see from above, they do.
Also, take special note of the packages path
configuration — this is the path to the directory where your OpenCV 3.0 bindings will be compiled and stored. After the running the make
command (detailed below), you’ll be checking in this directory for your OpenCV 3.0 bindings. In this case, my packages path
is lib/python3.2/site-packages
, so I’ll be checking /usr/local/lib/python3.2/site-packages
for my compiled output file.
All that’s left now is to compile OpenCV 3.0:
$ make -j4
Where the 4 corresponds to the 4 cores on our Raspberry Pi 2. Using multiple cores will dramatically speedup the compile time and bring it down from 2.8 hours to just above 1 hour!
Timings: 65m 33s
Assuming OpenCV has compiled without an error, you can now install it on your Raspberry Pi:
$ sudo make install $ sudo ldconfig
Timings: 39s
At this point OpenCV 3.0 has been installed on our Raspberry Pi!
However, we’re not quite done yet.
Remember how I mentioned the packages path
above?
Well, let’s list the contents of that directory and see if our OpenCV bindings are in there:
$ ls -l /usr/local/lib/python3.2/site-packages total 1416 -rw-r--r-- 1 root staff 1447637 Jun 22 18:26 cv2.cpython-32mu.so
Here we can see there is a file named cv2.cpython-32mu.so
, which is our actual Python bindings.
However, in order to use OpenCV 3.0 in our cv
virtual environment, we first need to sym-link the OpenCV binary into the site-packages
directory of the cv
environment:
$ cd ~/.virtualenvs/cv/lib/python3.2/site-packages/ $ ln -s /usr/local/lib/python3.2/site-packages/cv2.cpython-32mu.so cv2.so
So now when you list the contents of the site-packages
directory associated with our cv
virtual environment, you’ll see our OpenCV 3.0 bindings (the cv2.so
file):
And there you have it! OpenCV 3.0 with Python 3+ support is now successfully installed on your system!
Section 4: Verifying your OpenCV 3.0 install
Before we wrap this tutorial up, let’s ensure that our OpenCV bindings have installed correctly. Open up a terminal, enter the cv
virtual environment (or cv3
, if you followed the Python 2.7+ install steps), fire up your Python shell import OpenCV:
$ workon cv $ python >>> import cv2 >>> cv2.__version__ '3.0.0'
And sure enough, we can see OpenCV 3.0 with Python 3+ support has been installed on my Raspberry Pi:
What's next? We recommend PyImageSearch University.
84 total classes • 114+ hours of on-demand code walkthrough videos • Last updated: February 2024
★★★★★ 4.84 (128 Ratings) • 16,000+ Students Enrolled
I strongly believe that if you had the right teacher you could master computer vision and deep learning.
Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?
That’s not the case.
All you need to master computer vision and deep learning is for someone to explain things to you in simple, intuitive terms. And that’s exactly what I do. My mission is to change education and how complex Artificial Intelligence topics are taught.
If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to successfully and confidently apply computer vision to your work, research, and projects. Join me in computer vision mastery.
Inside PyImageSearch University you'll find:
- ✓ 86 courses on essential computer vision, deep learning, and OpenCV topics
- ✓ 86 Certificates of Completion
- ✓ 115+ hours of on-demand video
- ✓ Brand new courses released regularly, ensuring you can keep up with state-of-the-art techniques
- ✓ Pre-configured Jupyter Notebooks in Google Colab
- ✓ Run all code examples in your web browser — works on Windows, macOS, and Linux (no dev environment configuration required!)
- ✓ Access to centralized code repos for all 540+ tutorials on PyImageSearch
- ✓ Easy one-click downloads for code, datasets, pre-trained models, etc.
- ✓ Access on mobile, laptop, desktop, etc.
Summary
In this blog post, I have detailed how to install OpenCV 3.0 with Python 2.7+ and Python 3+ bindings on your Raspberry Pi 2. Timings for each installation step were also provided so you could plan your install accordingly. Just keep in mind that if you ever logout or reboot your Pi after setting up virtualenv
and virtualenvwrapper
that you’ll need to execute the workon
command to re-access your computer vision virtual environment prior to continuing the steps I have detailed. If you do not, you could easily find yourself in a situation with the dreaded ImportError: No module named cv2
error.
As the Raspberry Pi and the Raspbian/NOOBS operating system evolves, so will our installation instructions. If you run across any edge cases, please feel free to let me know so I can keep these install instructions updated.
And of course, in future blog posts we’ll be doing some really amazing projects using OpenCV 3.0 and the Raspberry Pi, so consider entering your email address in the form below to be notified when these posts go live!
Join the PyImageSearch Newsletter and Grab My FREE 17-page Resource Guide PDF
Enter your email address below to join the PyImageSearch Newsletter and download my FREE 17-page Resource Guide PDF on Computer Vision, OpenCV, and Deep Learning.