Friday, January 22, 2016

How to install OpenCV 3.1 for Python on Ubuntu 14.04

OpenCV 3.1 was just released a few weeks ago and features a wealth of new features, aggregated from GitHub community members, students and mentors, as well as the Google Summer of Code. Time to upgrade your installation!

Installing OpenCV can quickly turn into a nightmare, especially if you want to use either the latest code base or some non-standard options (such as features from the opencv_contrib repository or OpenNI support for depth sensors such as Microsoft Kinect). The following guide will show you how to install OpenCV 3.1 for Python with all its fancy options on Ubuntu 14.04 LTS (either via conda or from source) in ten easy steps!

( Step 0: Consider using the Python Anaconda distribution )

Actually the easiest way to install OpenCV is via the Python Anaconda distribution. If you're not going to need any of the optional OpenCV modules and plugins below, there is probably no need to install OpenCV from source. In this case, Anaconda is the way to go. In brief:

  1. Download and install Python Anaconda.
  2. Open up a terminal / command prompt (possibly with administrator rights).
  3. Create a new conda environment called "opencv" that will contain all necessary modules. Choose either python=2.7 or python=3.5:
    $ conda create -n opencv numpy scipy matplotlib python=3
  4. Activate the environment:
    $ source activate opencv
  5. Install OpenCV2:
    $ conda install opencv
    Or install OpenCV3:
    $ conda install opencv3
  6. If you get a "package not found" error, run an anaconda search:
    $ anaconda search -t opencv
    This will bring up a whole list of packages, each of which will list the exact version, the platform, and the user who has the package installed. Simply pick one from the list that works for your platform. For example, user trung has OpenCV 3.1.0 for linux-64 and win-64:
    $ conda install -c trung opencv3
    And done!

Step 1: Getting ready to install

If you want to install OpenCV from scratch, this is where you start. First you want to make sure that you have the latest packages installed:

$ sudo apt-get update
$ sudo apt-get upgrade

You also want to make sure you have the necessary build tools installed. build-essential is a reference for all the packages needed to compile a debian package. pkg-config is needed to compile software from its source code. cmake manages the build process of OpenCV.

$ sudo apt-get install build-essential cmake pkg-config

Step 2: Install Python libraries

In order to use OpenCV with Python, you need to have Python installed (duh). It's a good idea to include the ubiquitous NumPy and SciPy packages as there is almost no way you are going to use OpenCV-Python without them.

$ sudo apt-get install python-dev python-numpy
$ sudo apt-get install python-scipy

Step 3: Install GUI libraries and OpenGL extensions

OpenCV uses a library called HighGUI (which stands for "high-level graphical user interface") to open windows, display images, read and write images and videos, handle mouse and pointer events, etc. The library can either be powered with Qt or with the GIMP Toolkit (GTK). To use Qt as a back-end, run the following:

$ sudo apt-get install qt5-default
$ sudo apt-get install libqt5opengl5-dev

To use GTK as a back-end, run the following:

$ sudo apt-get install libgtk2.0-dev
$ sudo apt-get install libgtkglext1 libgtkglext1-dev

Step 4: Install image manipulation libraries

OpenCV supports a number of image manipulation libraries that will make your life a lot easier. For example, JasPer is a collection of libraries and application programs that allow for the coding and manipulation of diverse image formats. Other libraries exist to manipulate formats such as GIF, TIFF, PNG, BMP:

$ sudo apt-get install libpng3 pngtools libpng12-dev libpng12-0 libpng++-dev
$ sudo apt-get install libjpeg-dev libjpeg libjpeg-dbg libjpeg-progs
$ sudo apt-get install libtiff4-dev libtiff4 libtiffxx0c2 libtiff-tools
$ sudo apt-get install libjasper1-dev libjasper libjasper-runtime
$ sudo apt-get install zlib1g zlib1g-dbg zlib1g-dev

Step 5: Install video manipulation libraries

The same can be said for video manipulation libraries. For example, the libavformat library provides a generic framework for multiplexing and demultiplexing (muxing and demuxing) audio, video and subtitle streams (requires the libav codec). Xine is a free multimedia player that can play back CDs, DVDs, and VCDs as well as decode multimedia files like AVI, MOV, WMV, and MP3.

$ sudo apt-get install libavformat-dev libavutil51 libavutil-dev
$ sudo apt-get install libxine2-dev libxine2
$ sudo apt-get install libswscale-dev libswscale2
$ sudo apt-get install libdc1394-22 libdc1394-22-dev libdc1394-utils

In addition, you need to install the corresponding codecs:

$ sudo apt-get install libavcodec-dev
$ sudo apt-get install libfaac-dev libmp3lame-dev
$ sudo apt-get install libopencore-amrnb-dev libopencore-amrwb-dev
$ sudo apt-get install libtheora-dev libvorbis-dev libxvidcore-dev
$ sudo apt-get install ffmpeg x264 libx264-dev
$ sudo apt-get install libv4l-0 libv4l v4l-utils

Step 6: Install multi-processing libraries

OpenCV also supports TBB, a library for leveraging multi-core processor performance that abstracts platform details and threading mechanisms for performance and scalability, so you don't need to be a threading expert:

$ sudo apt-get install libtbb-dev

Step 7: Install OpenNI

If you want to use OpenCV in combination with a depth sensor such as the Microsoft Kinect 3D sensor or the Asus Xtion, you will need to install additional libraries. In order to use the Kinect, you can either go with OpenNI and SensorKinect, or with OpenKinect's libfreenect libraries.

libfreenect requires the following dependencies:

$ sudo apt-get install git-core freeglut3-dev
$ sudo apt-get install libxmu-dev libxi-dev libusb-1.0-0-dev

Then, download the latest source code from GitHub:

$ cd
$ git clone git://

Finally, you are ready to install the library using cmake:

$ cd libfreenect
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install
$ sudo ldconfig /usr/local/lib64/

To see if the installation was successful, connect your Kinect to our machine and run the demo:

$ sudo glview

If you choose to go with OpenNI, you might be disappointed to find that Apple bought PrimeSense in 2014 and subsequently shut down OpenNI. However, the community has preserved documentation and binaries of the old working source code. For example, you can find binaries for x86 and x64 platforms on Joseph Howse's website.

Step 8: Install OpenCV

Finally, you are ready to install OpenCV's core libraries. You can either download the zip package, or simply get the latest source code via git:

$ cd
$ git clone

This will make it easier to install future releases. All you need to do in the future is to make sure your local repository includes the latest updates:

$ git pull origin master

Then you are ready to install. This is where things can get hairy, as you will want to inform cmake about which optional modules to include. Specifically, you might want to compile a RELEASE version (without all the debugging options), include the extra modules (opencv_contrib), and add all the modules we installed above. In the end, the list of options can get quite long, such as the following:

$ mkdir build
$ cd build
 -DOPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \

But what if you can't remember or simply don't know the variable name of a specific option? That's where ccmake comes in handy. ccmake will allow you to use a graphical user interface for the cmake configuration process!

$ sudo apt-get install cmake-curses-gui
$ ccmake ..

When the GUI first opens, it will show EMPTY CACHE. Press the c key and cmake will start configuring. Now you will see a whole list of options (e.g., BUILD_EXAMPLES), which corresponds to the options you had to manually specify above. You can go through the list using the Up and Down keys, and press Enter to toggle their values. After you have specified everything there is to specify, press c again to configure the Makefile. If there are no errors, press g to generate the Makefile and exit. Careful: Make sure that you do not encounter any erros! Otherwise you might have to fix them by hand.

After cmake is done, a Makefile is generated. You can now sit back and watch the code compile. You can run the make processes multithreaded by adding -j:

$ make -j8

After make is done (make sure that it succeeded 100%), move the compiled source code to (what usually is) root-protected directories:

$ sudo make install

Note that if you want the opencv_contrib modules installed, you will need to repeat the procedure:

$ cd
$ git clone
$ cd opencv_contrib
$ mkdir build
$ cd build
$ ccmake ..
$ make -j8
$ sudo make install

Step 9: Finish off installation

Before you can use OpenCV, you need to tell Ubuntu where it can find the shared library files. For this, you can simply create a file opencv.conf that contains the name of the directory where all OpenCV library files are stored. Then, run ldconfig to make sure the changes take effect:

$ sudo /bin/bash -c 'echo "/usr/local/lib" > /etc/'
$ sudo ldconfig

Step 10: Verify installation

You can verify that the whole package was installed successfully by running some samples:

$ cd ~/opencv/samples
$ cmake .
$ make -j8
$ cd cpp
$ ./cpp-example-facedetect lena.jpg

All done. Finally!! Now you have OpenCV 3.1 installed on your computer with support for Python, TBB, OpenGL, video, 3D visualization, Qt/GTK, and much more.

How to install OpenCV 3.1 for Python on Windows or Fedora

Installing the latest OpenCV-Python package on Windows or Fedora is relatively straightforward, as you can choose to either install from source or use pre-built binaries.

If you are looking for additional resources, I can recommend Sebastian Montabone's tutorial from a while back (which focuses on OpenCV 2.4.9) and Joseph Howse's website that provides a list of useful binaries and Linux installation scripts.