In the last two years running the PyImageSearch blog, I have written two tutorials detailing the steps needed to install OpenCV (with Python links) on Ubuntu. You can find the two tutorials here:
Install OpenCV 3.0 and Python 2.7+ on Ubuntu 14.04 Install OpenCV 3.0 and Python 3.4+ on Ubuntu 14.04 However, with Ubuntu 14.04 support
- ending
- and Ubuntu 16.04
set as the next LTS (with support until April 2021), I thought it would be appropriate to create a new, updated Ubuntu + OpenCV installation tutorial.
Within this tutorial, I will document, demonstrate, and provide detailed steps to install OpenCV 3 on Ubuntu 16.04 with Python 2.7 or Python 3.5 bindings.
Also, this document has been completely updated from my previous Ubuntu 14.04 tutorials to use the latest updated packages from the apt-get repository.
To learn how to install OpenCV on your Ubuntu 16.04 system, read on.
Note: Don’t care about Python bindings and simply want OpenCV installed on your system (probably for C++ encoding)? Don’t worry, this tutorial will still work for you. Follow the instructions and perform the steps: by the end of this article, you will have OpenCV installed on your system. From there, simply ignore Python bindings and proceed as usual.
Ubuntu 16.04
: How to Install OpenCV
Before we get into this tutorial, I want to mention that Ubuntu 16.04 actually ships out of the box with Python 2.7 and Python 3.5 installed. The actual versions (as of October 24, 2016) are:
Python
- 2.7.12 (used by default when you type python in your terminal
- Python 3.5.2 (can be accessed via the python3 command).
).
Again, it bears repeating that Python 2.7 is still the default version of Python used by Ubuntu. There are plans to migrate to Python 3 and use Python 3 by default; However, as far as I can tell, we are still a long way from that actually becoming a reality.
In either case, this tutorial will support Python 2.7 and Python 3. I’ve highlighted the steps that require you to make a decision regarding which version of Python you’d like to use. Make sure you are consistent with your decision, otherwise you will inevitably encounter compile, link, and import errors.
Regarding which version of Python you should use… I’m not going to go into that argument. I will simply say that you should use whatever version of Python you are comfortable with and use on a daily basis. Keep in mind that Python 3 is the future, but also keep in mind that porting Python 2.7 code to Python 3 isn’t a terrible challenge either once you understand the differences between Python versions. And as far as OpenCV goes, OpenCV 3 doesn’t care what version of Python you’re using: the links will work the same.
All that said, let’s start installing OpenCV with Python bindings on Ubuntu 16.04.
Step #1: Install OpenCV Dependencies on Ubuntu 16.04
Most (in fact, all) of the steps in this tutorial will be carried out using your terminal. To get started, open
your command line and update the apt-get package manager to update and update and preinstall packages/libraries: $ sudo apt-get update $ sudo apt-get upgrade Next,
let’s install some development tools:
$ sudo apt-get install build-essential cmake pkg-config
The pkg-config package is already (most likely) installed on your system, but be sure to include it in the apt-get command above just in case. The cmake program is used to automatically configure our OpenCV build.
OpenCV is an image processing and computer vision library. Therefore, OpenCV must be able to load various image file formats from disk, such as JPEG, PNG, TIFF, etc. To load these images from disk, OpenCV calls other image I/O libraries that really make the loading and decoding process easier. We install the necessary ones below:
$ sudo apt-get install libjpeg8-dev libtiff5-dev libjasper-dev libpng12-dev
Okay, now we have libraries to load images from disk, but what about video? Use the following commands to install packages used to render video streams and access camera frames:
$ sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev $ sudo apt-get install libxvidcore-dev libx264-dev
OpenCV ships ready to use with a very limited set of GUI tools. These GUI tools allow us to display an image to our screen (cv2.imshow), wait/record keystrokes (cv2.waitKey), track mouse events (cv2.setMouseCallback), and create simple GUI elements such as sliders and trackbars. Again, you shouldn’t expect to be building full-fledged GUI applications with OpenCV – these are just simple tools that allow you to debug your code and create very simple applications.
Internally, the name of the module that handles OpenCV GUI operations is highgui. The highgui module is based on the GTK library, which you must install using the following command
: $ sudo apt-get install libgtk-3-dev Next, we install libraries that
are used to optimize various functionalities within OpenCV, such as matrix operations:
$ sudo apt-get install libatlas-base-dev gfortran
We’ll conclude Step #1 by installing the Python development headers and libraries for Python 2.7 and Python 3.5 (that way you have both):
$ sudo apt-get install python2.7-dev python3.5-dev
Note: If you don’t install the Python development headers and static library, you will have problems during Step #4 where we run cmake to set up our build. If these headers are not installed, the cmake command will not be able to automatically determine the appropriate values for the Python interpreter and Python libraries. In short, the output in this section will look “empty” and you won’t be able to create the Python bindings. When you get to Step #4, take the time to compare the output of the command with mine.
Step #2: Download
the OpenCV Feed At the time of publication of this article, the most recent version of OpenCV
is 3.1.0, which we downloaded a .zip of and unarchived using the following commands:
$cd~$wget -O opencv.zip https://github.com/Itseez/opencv/archive/3.1.0.zip$unzip opencv.zip
When new versions of OpenCV are released, you can check the official OpenCV GitHub and download the latest version by changing the version number of the .zip.
However, we haven’t finished downloading the source code yet, we also need the repository opencv_contrib:
$wget -O opencv_contrib.zip https://github.com/Itseez/opencv_contrib/archive/3.1.0.zip$unzip opencv_contrib.zip
Why do we bother downloading the contrib repository as well?
Well, we want the entire OpenCV 3 installation to have access to features (no pun intended) like SIFT and SURF. In OpenCV 2.4, SIFT and SURF were included in the default installation of OpenCV. However, with the release of OpenCV 3+, these packages have been moved to contrib, which houses (1) modules that are currently under development or (2) modules that are marked as “non-free” (i.e. proprietary). You can learn more about the reasoning behind the restructuring of SIFT/SURF in this blog post.
Note: You may need to expand the above commands using the “<=>” button during copy and paste. The .zip in .zip 3.1.0 may be cut off in smaller browser windows. For convenience, I have included the full URL of both the opencv file and the opencv_contrib file below:
- https://github.com/Itseez/opencv/archive/3.1.0.zip
- https://github.com/Itseez/opencv_contrib/archive/3.1.0.zip
I also want to mention that both your opencv version and opencv_contrib must be the same (in this case, 3.1.0). If the version numbers don’t match, you could easily run into compile-time errors (or worse, runtime errors that are nearly impossible to debug).
Step #3: Set Up Your Python Environment – Python 2.7 or Python 3
Now we’re ready to start setting up our Python development environment for compilation. The first step is to install pip
, a Python package manager: $cd~$wget https://bootstrap.pypa.io/get-pip.py$sudo python get-pip.py I’ve
mentioned this in every OpenCV+Python installation tutorial I’ve done, but I’ll say it again here today: I’m a big fan of virtualenv and virtualenvwrapper. These Python packages allow you to create separate and independent Python environments for each project you are working on.
In short, using these packages allows you to solve the dilemma “Project X depends on version 1.x, but Project Y needs dilemma 4.x. A fantastic side effect of using Python virtual environments is that you can keep your Python system clean, tidy, and clutter-free.
While you can certainly install OpenCV with Python bindings without Python virtual environments, I recommend you use them as other PyImageSearch tutorials take advantage of Python virtual environments. I will also assume that you have virtualenv and virtualenvwrapper installed for the rest of this guide.
If you want a full and detailed explanation of why Python virtual environments are a best practice, you should read this excellent blog post about RealPython. I also provide some feedback on why I personally prefer Python virtual environments in the first half of this tutorial.
Again,
let me reiterate that it is standard practice in the Python community to take advantage of virtual environments of some kind, so I suggest you do the same
: $ sudo pip install virtualenv virtualenvwrapper $ sudo rm -rf ~/get-pip.py ~/.cache/pip
Once we have virtualenv and virtualenvwrapper installed, we need to update our ~/.bashrc file to include the following lines at the bottom of the file:
# virtualenv and virtualenvwrapper export WORKON_HOME=$HOME/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh
The ~/.bashrc file is simply a shell script that Bash runs every time you start a new terminal. This file is typically used to configure various settings. In this case, we are setting an environment variable called WORKON_HOME to point to the directory where our Python virtual environments live. Then we load any necessary configuration from virtualenvwrapper.
To update your ~/.bashrc file simply use a standard text editor. I would recommend using nano, vim or emacs. You can also use graphic editors, but if you’re just starting out, nano is probably the easiest to operate.
A simpler solution is to use the cat command and avoid editors altogether
: $ echo -e “\n# virtualenv and virtualenvwrapper” >> ~/.bashrc $ echo “export WORKON_HOME=$HOME/.virtualenvs” >> ~/.bashrc $ echo “source /usr/local/bin/virtualenvwrapper.sh” >> ~/.bashrc After editing our ~/.bashrc
file, we need to reload the changes: $ source ~/.bashrc
Note: The source code call in .bashrc only needs to be done once for our current shell session. Every time we open a new terminal, the content of .bashrc will run automatically (including our updates).
Now that we have installed virtualenv and virtualenvwrapper, the next step is to actually create the Python virtual environment: we do this using the mkvirtualenv command.
But before you run this command, you need to make a decision: Do you want to use Python 2.7 or Python 3?
The result of your choice will determine which command you will execute in the next section.
Creating the Python Virtual Environment If you decide to use Python 2.7, use the following command to create a Python
2.7
virtual environment: $ mkvirtualenv cv -p python2 Otherwise, use this command to create a Python 3 virtual environment: $ mkvirtualenv cv -p python3
Regardless of which Python command you decide to use, the end result is that we have created a Python virtual environment called cv (short for “computer vision”).
You can name this virtual environment whatever you want (and create as many Python virtual environments as you want), but for the time being, I’d suggest sticking with the cv name, as that’s what I’ll be using for the rest of this tutorial.
Verifying that you are in
the virtual environment “cv”
If you ever restart your Ubuntu system; log out and log back in; or open a new terminal, you will need to use the workon command to access your virtual environment cv again. The following is an example of
the workon command: $ workon cv To validate that you are in the cv virtual environment, simply examine your command line: If you see the text (cv) preceding your message, then you are in the cv virtual environment: Figure 1: Make sure you see the text “(cv)” in your message, indicating that
you
Otherwise, if you don’t see the cv text, then you’re not in the cv virtual environment:
simply use the workon command mentioned above.
Install NumPy in your Python virtual environment
The final step before compiling OpenCV is to install NumPy, a Python package used for numerical processing. To install NumPy, make sure you are in the cv virtual environment (otherwise, NumPy will be installed in the Python system version instead of the cv environment). From there, run the following command
: $ pip install numpy
Step #4: Configure and build OpenCV on Ubuntu 16.04
At this point, all our necessary prerequisites have been installed: we are now ready to compile and OpenCV!
But before you do that, verify that you are in the cv virtual environment by examining your message (you should see the text (cv) that precedes it), and if not, use the command
workon: $ workon cv
After making sure you are in the virtual environment cv, we can install and configure our build using CMake:
$ cd ~/opencv-3.1.0/ $ mkdir build $ cd build $ cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D INSTALL_PYTHON_EXAMPLES=ON \ -D INSTALL_C_EXAMPLES=OFF \ -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib-3.1.0/modules \ -D PYTHON_EXECUTABLE=~/.virtualenvs/cv/bin/python \ -D BUILD_EXAMPLES=ON ..
The above commands change the directory to ~/opencv-3.1.0, which if you’ve been following this tutorial is where you downloaded and unarchived the .zip files.
Note: If you receive an error related to stdlib.h: There is no such file or directory during the cmake or make phase of this tutorial, you must also include the following option for CMake: -D ENABLE_PRECOMPILED_HEADERS=OFF. In this case, I would suggest deleting your build directory, recreating it, and then running CMake again with the above option included. This will resolve the stdlib.h error. Thanks to Carter Cherry and Marcin for pointing this out in the comments section!
Within this directory we create a subdirectory called build and change it. The build directory is where the actual build will take place.
Finally, we run cmake to configure our build.
Before moving on to the actual OpenCV build, be sure to examine the output of CMake!
To do this, scroll down in the section titled Python 2 and Python 3.
If you are compiling OpenCV on Ubuntu 16.04 with Python 2.7 support, make sure the Python 2 section includes valid paths to the Interpreter, Libraries, numpy, and packages path. Your output should look similar to mine below
: Figure 3:
.
When you examine this output, you can see that:
The interpreter points to the Python 2.7 binary in the cv virtual environment. The
- libraries point to the Python 2.7 library (which we installed during the final step of Step #1). The
- numpy value points to our installation of NumPy in the cv virtual environment
- points
- to lib/python2.7/site-packages. When combined with the CMAKE_INSTALL_PREFIX, this means that after compiling OpenCV, we will find our cv2.so links in /usr/local/lib/python2.7/site-packages/.
. And finally, the package path
Similarly, if you’re compiling OpenCV 16.04 with Python 3 support,
you’ll want to make sure your Python 3 section looks similar to mine below: Figure 4: Validation that Python 3 will be used when compiling OpenCV 3 for Ubuntu 16.04
.
Again, notice how my interpreter, libraries, numpy, and package path have been configured correctly.
If not sees the cv virtual environments in these variable paths, it is almost certain that you are NOT in the cv virtual environment before running CMake!
If that’s really the case, simply access the cv virtual environment by calling workon cv and run the CMake command mentioned above again.
Assuming your CMake command came out without any error, you can now
compile OpenCV:$ make -j4
The -j switch controls the number of processes that will be used when compiling OpenCV — you’ll want to set this value to the number of processors/cores on your machine. In my case, I have a quad-core processor, so I set -j4.
Using multiple processes allows OpenCV to compile faster; however, there are times when race conditions are affected and compilation is extended. While you can’t really tell if this is the case without a lot of prior experience compiling OpenCV, if you run into a bug, my first suggestion would be to run make clean to flush the build, followed by compiling using just one kernel
: $make clean$make
Below you can find a screenshot of a successful OpenCV+Python build on Ubuntu 16.04:
Figure 5: Successfully compiling OpenCV 3 for Ubuntu 16.04.
The last step is to
install OpenCV 3 on Ubuntu 16.04: $ sudo make install $ sudo ldconfig
Step #5: Finish Your
OpenCV Installation
You’re going down the home stretch, just a few more steps to go and your Ubuntu 16.04 system will be configured with OpenCV 3
. For Python
After running sudo make install, your Python 2.7 bindings for OpenCV 3 should now be located in /usr/local/lib/python-2.7/site-packages/. You can verify this using the command
ls: $ ls -l /usr/local/lib/python2.7/site-packages/ total 1972 -rw-r-r-1 root staff 2016608 Sep 15 09:11 cv2.so Note: In some cases, you may find that OpenCV was installed in /usr/local/lib/python2.7/dist-packages
instead of /usr/local/lib/python2.7/site-packages (note dist-packages versus site-packages). If the cv2.so bindings are not in the site-packages directory, be sure to check dist-pakages.
The final step is to symbolically link
our OpenCV cv2.so links in our virtual environment cv for Python 2.7: $ cd ~/.virtualenvs/cv/lib/python2.7/site-packages/ $ ln -s /usr/local/lib/python2.7/site-packages/cv2.so cv2.so For Python 3.5
:
After running sudo make install, your OpenCV + Python 3 bindings should be located in /usr/local/lib/python3.5/site-packages/. Again, you can verify this using the command
ls: $ ls -l /usr/local/lib/python3.5/site-packages/ total 1972 -rw-r-r- 1 root staff 2016816 Sep 13 17:24 cv2.cpython-35m-x86_64-linux-gnu.so
I’ve been puzzled about this behavior since OpenCV 3 was released, but for some reason, when compiling OpenCV with Python 3 support, the output cv2.so filename is different. The actual filename may vary for you, but it should look similar to cv2.cpython-35m-x86_64-linux-gnu.so.
Again, I have no idea exactly why this happens, but it’s a very easy solution. All we need to do is
rename the file: $cd/usr/local/lib/python3.5/site-packages/ $sudo mv cv2.cpython-35m-x86_64-linux-gnu.so cv2.so After renaming cv2.cpython-35m-x86_64-linux-gnu.so
to simply cv2.so, we can symbolically link our OpenCV links in the cv virtual environment for Python 3.5
: $ cd ~/.virtualenvs/cv/lib/python3.5/site-packages/ $ ln -s /usr/local/lib/python3.5/site-packages/cv2.so
cv2.so Step #6: Test OpenCV
installation
Congratulations, you now have OpenCV 3 installed on your Ubuntu 16.04 system!
To verify that the installation works:
- Open a new terminal
- Run the workon command to access the cv virtual environment
- Try importing the Python + OpenCV links.
.
Python.
I have demonstrated how to perform these steps below
: $ cd ~ $ workon cv $ python Python 3.5.2 (default, Jul 5 2016, 12:43:10) [GCC 5.4.0 20160609] on linux Type “help”, “copyright”, “credits” or “license” for more information. >>> import cv2 >>> cv2.__version__ ‘3.1.0’ >>> As you can see, I can import my OpenCV links into my Python 3.5 shell.
Below is a screenshot of me using the same steps described
in this tutorial and importing OpenCV bindings into a Python 2.7 shell:
So, regardless of which version of Python you decide to use, simply follow the detailed steps in this tutorial and you will be able to install OpenCV+ Python on your Ubuntu 16.04 system.
Once OpenCV is installed, you can delete the opencv-3.1.0 and opencv_contrib-3.1.0 directories (along with their associated .zip files): $cd ~ $rm -rf opencv-3.1.0
opencv_contrib-3.1.0 opencv
.zip opencv_contrib.zip
But again, be careful when running this command! You’ll want to make sure you’ve properly installed OpenCV on your system before blowing along these directories. Otherwise, you will need to restart the entire build process.
Troubleshooting
and FAQ
In this section, I address some of the common questions, issues, and issues that arise when installing OpenCV on Ubuntu 16.04.
Q. When I run mkvirtualenv or workon, I get a “command not found error”.
A. There are three main reasons why you would receive this error message, all of which are related to Step #3:
- First, make sure you have installed virtualenv and virtualenvwrapper using the pip package manager. You can verify this by running pip freeze, examining the output and making sure to see virtualenv and virtualenvwrapper in the list of installed packages.
- The ~/.bashrc file may not update correctly. To diagnose this, use a text editor like nano and view the contents of your ~/.bashrc file. At the bottom of the file, you should see that proper export and source commands are present (again, check Step #3 for commands that need to be added to ~/.bashrc).
- After editing your ~/.bashrc file, you may have forgotten to get it and reload its contents. Be sure to run source ~/.bashrc after editing it to make sure the content is reloaded, this will give you access to the mkvirtualenv and workon commands.
Q. Every time I open a new terminal, log out or restart my Ubuntu system, I cannot execute the mkvirtualenv or workon commands
.
A. See reason #2 for the previous question.
Q. When I (1) open a Python shell that imports OpenCV
or (2) run a Python script that calls OpenCV, I get an error: Import error: No module named cv2.
A. Unfortunately, the exact cause of this error message is extremely difficult to diagnose, as there are several reasons why this could be happening. In general, I recommend the following suggestions to help diagnose and resolve the error:
- Ensure that you are in the cv virtual environment by using the workon cv command. If this command gives you an error, see the first question in this FAQ.
- If after making sure that your ~/.bashrc file has been successfully updated and source ‘d, try investigating the contents of the site-packages directory in your virtual environment cv. You can find the site-packages directory at ~/.virtualenvs/cv/lib/python2.7/site-packages/ or ~/.virtualenvs/cv/lib/python3.5/site-packages/ depending on your Python version. Ensure that (1) there is a cv2.so file in this site-packages directory and (2) that it is correctly linked to a valid existing file.
- Be sure to check the site-packages directory (and even dist-packages) for the Python system installation located at /usr/local/lib/python2.7/site-packages/ and /usr/local/lib/python3.5/site-packages/, respectively. Ideally, you should have a cv2.so file there.
- If all else fails, check your build/lib directory of your OpenCV build. There should be a file cv2.so there (as long as both cmake and make run without errors). If the cv2.so file is present, manually copy it to both the site-packages directory on the system and the site-packages directory for the cv virtual environment.
Summary
In today’s blog post, I demonstrated how to install OpenCV 3 with Python 2.7 or Python 3 bindings on your Ubuntu 16.04 system.
For more tutorials on installing OpenCV on
other operating systems (such as OSX, Raspbian, etc.), see this page where I provide additional links and resources.
But before you go…
If you’re interested in learning more about OpenCV, Computer Vision, and Image Processing, be sure to enter your email address in the form below to receive notifications when new posts are published from blog.
