Installing Opencv on Ubuntu (for use with python)

Summary

OpenCV is a really good library to use for processing video files and real time video sources from a webcam in python.

Setting it up, however (at least on ubuntu), can be a little tricky. It is not actually a python library that can be installed using pip. And relying on your operating system's package manager will likely install an out of date version.

This post will guide you through the steps needed to install the latest version from source.

Versions : This has been tested to work on Ubuntu 14.04, OpenCV 3.3.0 and python 2.7 and python 3.4. But it should work with more rescent versions of Ubuntu, and hopefully future versions of OpenCV.

Getting the source package url

First, we want to find out what versions are available. We can go to http://opencv.org/releases.html to find this out. Once you have decided what version you want to use (most likely the latest version), you will want to get the URL of the zipped up file for the source code of that release.

Simply right-click on the Sources link, and select copy link address. You will then want to paste that into a text editor, as we will be using it to set some variables in the terminal.

Modify the following two lines to reflect the URL of the version you have chosen. The CV_SOURCE_PACKAGE variable should be exactly the same name as what is at the end of the URL.

# VARIABLES
CV_SOURCE_URL="https://github.com/opencv/opencv/archive/3.3.0.zip"
CV_SOURCE_PACKAGE="3.3.0.zip"

WARNING : Note that there should be no spaces on either side of the equality sign when declaring a value for a variable. That might work fine in python, but not for bash commands.

Now copy and paste that into your terminal window.

Next, we need to specify where we will store the temporary files during installation. We will store the downloaded zip file here, and later create a subdirectory for compiling the source code.

TEMP_DIR="/tmp"  # where to store the source files temporarily

Dependencies

Firstly, we should update the package repositories database.

sudo apt-get update

Next, we need to install some basic development libraries.

# DEVELOPMENT LIBRARIES
sudo apt-get install -y build-essential cmake gcc swig pkg-config
sudo apt-get install -y python-dev
sudo apt-get install -y wget unzip

We will also need to install some video processing and codec libraries:

# GUI AND CAMERA DEPENDENCIES
sudo apt-get install -y libgtk2.0-dev
sudo apt-get install -y libdc1394-dev
sudo apt-get install -y libavcodec-dev libavformat-dev
sudo apt-get install -y libswscale-dev libavresample-dev
sudo apt-get install -y libv4l-dev ffmpeg-dev
sudo apt-get install -y gstreamer-plugins-base1.0-dev

Next, some image processing and codec libraries:

# IMAGE DEPENDENCIES
sudo apt-get install -y libtiff4-dev libjasper-dev libpng12-dev
sudo apt-get install -y libjpeg8-dev libjpeg-turbo8-dev
sudo apt-get install -y libopenexr-dev
sudo apt-get install -y libwebp-dev
sudo apt-get install -y libprotobuf-dev
sudo apt-get install -y libgphoto2-6 libgphoto2-dev

Next, ensuring we have numpy and scipy (which are needed by openCV):

# INSTALLING PYTHON DEPENDENCIES
sudo apt-get install -y libopenblas-dev         # Speeds up numpy/scipy
sudo apt-get install -y liblapack-dev gfortran  # Needed for scipy/numpy
sudo apt-get install -y python-numpy python3-numpy
sudo apt-get install -y python-scipy python3-scipy

Finally, some optimization libraries to make openCV faster.

# INSTALLING OPTIMIZATION DEPENDENCIES"
# Intel's Threading Building Blocks (TBB) - For parallelization
sudo apt-get install -y libtbb-dev

# Eigen - for optimized math operations.
sudo apt-get install -y libeigen3-dev

Downloading the source code

We can now download the source zip.

# NAVIGATE TO THE TEMPORARY DIRECTORY
mkdir -p ${TEMP_DIR}  # create the temporary dir if it doesn't exist
cd ${TEMP_DIR}        # move into the temporary dir

# DOWNLOAD THE SOURCE FILES
wget -c ${CV_SOURCE_URL}

Then once it is downloaded, we can extract it into a subdirectory, which we will call opencv_source_files, and then navigate into it.

# EXTRACT THE SOURCE FILES
unzip ${CV_SOURCE_PACKAGE} -d opencv_source_files
cd opencv_source_files/opencv*

Compiling the source code.

This is the daunting bit. But it doesn't actually have to be hard. Hopefully, the steps I go through will make things easy to understand.

In order to compile from source, we need to go through several steps:

1. Build : (Create the configuration files that contain all the settings needed to create the binary executable files)
2. Make : (Create the binary executable files)
3. Install : (Place the binary files into the appropriate locations on your computer)

1. Build the configuration files

We will create a place to store the build settings. It will just be a subdirectory, which we will call build, and we will navigate into it.

# CREATE THE BUILD DIRECTORY
mkdir build
cd build

We will use cmake to create the settings, and we will specify some of the values using flags. The syntax used is as follows:

cmake -D FLAG1=Value -D FLAG2=Value -D FLAG2=Value ..

Each flag starts with a -D, followed by the flag name, and its value. We tell cmake that we have reached the end by putting two dots (..) at the very end.

Since we will be setting lots of flags, we can use the back slash \ to continue the contents of a line onto the next one. This will make things easy to read and understand.

cmake \
    -D CMAKE_BUILD_TYPE=RELEASE\
    -D CMAKE_INSTALL_PREFIX=/usr/local\
    -D INSTALL_C_EXAMPLES=OFF\
    -D INSTALL_PYTHON_EXAMPLES=ON\
    -D BUILD_TESTS=OFF\
    -D BUILD_PERF_TESTS=OFF\
    -D BUILD_EXAMPLES=OFF\
    -D WITH_TBB=ON\
    -D WITH_EIGEN=ON\
    ..

Here is an explanation of the settings used:

• CMAKE_BUILD_TYPE=RELEASE : Release mode, as opposed to debug mode
• CMAKE_INSTALL_PREFIX=/usr/local : Where the files are to be installed
• INSTALL_C_EXAMPLES=OFF : Do not create C examples
• INSTALL_PYTHON_EXAMPLES=ON : Include Python Examples
• BUILD_TESTS=OFF : Disable tests
• BUILD_PERF_TESTS=OFF : As above
• WITH_TBB=ON : Make use Intel's Threading Building Blocks (TBB), a library we installed in the dependencies section. This enables parallelization to speed things up.
• WITH_EIGEN=ON : Make use of the Eigen library, which we installed in the dependencies section. This allows for optimized math operations.

Once those lines are run on the terminal, it should print out some lines that give a summary of the settings, as well as whether the dependencies have been met.

The important lines to look at are as shown below, make sure that you have something similar.

--   GUI:
--     GTK+ 2.x:                    YES (ver 2.24.23)
--     GThread :                    YES (ver 2.40.2)

--   Media I/O:
--     ZLib:                        /usr/lib/x86_64-linux-gnu/libz.so (ver 1.2.8)
--     JPEG:                        /usr/lib/x86_64-linux-gnu/libjpeg.so (ver )
--     WEBP:                        /usr/lib/x86_64-linux-gnu/libwebp.so (ver encoder: 0x0202)
--     PNG:                         /usr/lib/x86_64-linux-gnu/libpng.so (ver 1.2.50)
--     TIFF:                        /usr/lib/x86_64-linux-gnu/libtiff.so (ver 42 - 4.0.3)
--     JPEG 2000:                   /usr/lib/x86_64-linux-gnu/libjasper.so (ver 1.900.1)

--   Video I/O:
--     DC1394 2.x:                  YES (ver 2.2.1)
--     FFMPEG:                      YES
--       avcodec:                   YES (ver 54.35.1)
--       avformat:                  YES (ver 54.20.4)
--       avutil:                    YES (ver 52.3.0)
--       swscale:                   YES (ver 2.1.1)
--       avresample:                YES (ver 1.0.1)
--     GStreamer:
--       base:                      YES (ver 1.2.4)
--       video:                     YES (ver 1.2.4)
--       app:                       YES (ver 1.2.4)
--       riff:                      YES (ver 1.2.4)
--       pbutils:                   YES (ver 1.2.4)
--     V4L/V4L2:                    NO/YES
--     gPhoto2:                     YES

--   Parallel framework:            TBB (ver 4.2 interface 7000)

--   Other third-party libraries:
--     Use Intel IPP:               2017.0.2 [2017.0.2]
--                at:               /tmp/cv/opencv_source_files/opencv-3.3.0/build/3rdparty/ippicv/ippicv_lnx
--     Use Lapack:                  NO
--     Use Eigen:                   YES (ver 3.2.0)
--     Use Cuda:                    NO
--     Use OpenCL:                  YES

--   Python 2:
--     Interpreter:                 /usr/bin/python2.7 (ver 2.7.6)
--     Libraries:                   /usr/lib/x86_64-linux-gnu/libpython2.7.so (ver 2.7.6)
--     numpy:                       /usr/local/lib/python2.7/dist-packages/numpy/core/include (ver 1.11.0)
--     packages path:               lib/python2.7/dist-packages
--
--   Python 3:
--     Interpreter:                 /usr/bin/python3.4 (ver 3.4.3)
--     Libraries:                   /usr/lib/x86_64-linux-gnu/libpython3.4m.so (ver 3.4.3)
--     numpy:                       /usr/local/lib/python3.4/dist-packages/numpy/core/include (ver 1.11.0)
--     packages path:               lib/python3.4/dist-packages
--
--   Python (for build):            /usr/bin/python2.7

2. Make the binary executable files

Now that the configuration files have been created using cmake, we can actually compile the source code to make the executable files.

In order to speed up the compilation process, we can choose to use multiple cores. Modify the following variable to however many CPU cores you feel comfortable using up. If you are uncertain how many cores your computer has, then just set it to 1 to be safe.

# COMPILING FROM SOURCE FILES
NCORES=4          # Number of CPU cores to use during compiling
make -j${NCORES}

3. Install

Now that the binary files have been created within the subdirectory, we have to move them to locations our computer will recognize. This is the installation process.

# INSTALLING THE COMPILED BINARIES
sudo make install
sudo ldconfig

Linking up to Python

If you are using OpenCV version 3.3.0 (and hopefully newer versions), then the installation process should have automatically recognized all the python versions you are using and put the relevant files in the right place. This should allow python to recognize OpenCV as a library that can be imported, like any other python library.

You can test if it was installed properly by going into python, and running:

import cv2  # Yes! cv2, even if you are using openCV 3.x (confusing, I know!)
print(cv2.__version__)

[OUTPUT]
3.3.0

Ideally, it should print out the version of OpenCV you tried to install. If it did, then you are done! That's pretty much it. You can now jump to the clearing temporary files section.

If however, it threw some error message about not being able to import cv2, or you got a different version, then you will need to manually find the OpenCV library file for python and move it to a place python will recognize.

You will need to look for where Open CV placed a *.so file. For Python 2.x, this file is named cv2.so, and for python 3.x series, it is named something like cv2.cpython-34m.so or cv2.cpython-35m.so depending on the particular python 3.x version you are using.

Older versions of OpenCV usually placed the *.so file somewhere in the python subdirectory of /usr/local/lib/, in a directory called site-packages. Eg, for python 2.7, it would be located at /usr/local/lib/python2.7/site-packages/cv2.so.

We can move this file to somewhere python will recognize by creating a link
to this file from the dist-packages subdirectory located in the python
directory at /usr/lib/. Eg:

cd /usr/lib/python2.7/dist-packages/
sudo ln -s -f /usr/local/lib/python2.7/site-packages/cv2.so cv2.so

For python 3.4 we might do something like:

cd /usr/lib/python3/dist-packages
sudo ln -s -f /usr/local/lib/python3.4/site-packages/cv2.cpython-34m.so cv2.cpython-34m.so

Clearing temporary files

You should hopefully have things working now. If so, then we can delete the temporary files now.

# REMOVING TEMPORARY INSTALLATION FILES
cd ${TEMP_DIR}
rm ${CV_SOURCE_PACKAGE}
rm -rf opencv_source_files

Virtualenvs

This section is only relevant for those of you wanting to use OpenCV from within a python virtualenv environment.

Assuming you set up the virtual environment using the --system-site-packages flag, as in something like this:

virtualenv -p /usr/bin/python2.7 --system-site-packages  myVirtualEnv

Then, everything should work just fine. You should have access to OpenCV from your virtual environment.

If you didn't use that flag, then you can try one of the following two options:

1. Allow global site-packages
2. Link the OpenCV *.so file manually.

OPTION 1 - Allow global site-packages

This option will give your virtual environment access to libraries you have in your default system python installation. When you do not use the --system-site-packages flag, it creates a text file called no-global-site-packages.txt that blocks any non-core python libraries that are installed in the system's default python directory.

In order, to enable access those libraries, you can just delete that file manually. The file will be located at something along the lines of:

/PATH/TO/MY_VIRTUALENV/lib/python2.7/no-global-site-packages.txt

OPTION 2 - Link the OpenCV *.so file manually

In the previous section, about Linking up to Python, I discussed how you could find where the *.so file is located, and how to create a link to a directory that python recognizes. You can do the same thing, and create a link to the *.so file from a directory that your virtualenv will recognize, eg:

cd /PATH/TO/MY_VIRTUALENV/lib/python2.7/site-packages/
ln -s -f /usr/local/lib/python2.7/site-packages/cv2.so cv2.so

Automation

The entire process can be automated by creating a single bash script, and running it. Just make sure you modify the variable values to suit your needs before you run it.

################################################################################
#                                    VARIABLES
################################################################################
CV_SOURCE_PACKAGE="3.3.0.zip"
CV_SOURCE_URL="https://github.com/opencv/opencv/archive/${CV_SOURCE_PACKAGE}"
TEMP_DIR="/tmp/cv"  # where to store the source files temporarily
NCORES=4            # Number of CPU cores to use during compiling of source code

################################################################################
#                                    FAILSAFE
################################################################################
# terminate script if any line returns a non-zero exit status
set -e

################################################################################
#                                   DEPENDENCIES
################################################################################
echo "\n========================================================="
echo "INSTALLING DEV DEPENDENCIES"
echo "=========================================================\n"
sudo apt-get update
#sudo apt-get upgrade -y

sudo apt-get install -y build-essential cmake gcc swig pkg-config #gcc-c++
sudo apt-get install -y python-pip python-dev python-wheel python-virtualenv
sudo apt-get install -y unzip

echo "\n========================================================="
echo "INSTALLING GUI AND CAMERA DEPENDENCIES"
echo "=========================================================\n"
sudo apt-get install -y libgtk2.0-dev
sudo apt-get install -y libdc1394-dev
sudo apt-get install -y libavcodec-dev libavformat-dev
sudo apt-get install -y libswscale-dev libavresample-dev
sudo apt-get install -y libv4l-dev ffmpeg-dev
sudo apt-get install -y gstreamer-plugins-base1.0-dev

echo "\n========================================================="
echo "INSTALLING IMAGE DEPENDENCIES"
echo "=========================================================\n"
sudo apt-get install -y libtiff4-dev libjasper-dev libpng12-dev
sudo apt-get install -y libjpeg8-dev libjpeg-turbo8-dev
sudo apt-get install -y libopenexr-dev
sudo apt-get install -y libwebp-dev

sudo apt-get install -y libprotobuf-dev
sudo apt-get install -y libgphoto2-6 libgphoto2-dev

echo "\n========================================================="
echo "INSTALLING PYTHON DEPENDENCIES"
echo "=========================================================\n"
sudo apt-get install -y libopenblas-dev  # Speeds up numpy/scipy
sudo apt-get install -y liblapack-dev gfortran # Needed for scipy/numpy
sudo apt-get install -y python-numpy python3-numpy
sudo apt-get install -y python-scipy python3-scipy

echo "\n========================================================="
echo "INSTALLING OPTIMIZATION DEPENDENCIES"
echo "=========================================================\n"
# Intel's Threading Building Blocks (TBB) - For parallelization
# Cmake configuration: -D WITH_TBB=ON
sudo apt-get install -y libtbb-dev

# Eigen for optimized mathematical operations.
#  Cmake configuration: -D WITH_EIGEN=ON
sudo apt-get install -y libeigen3-dev

################################################################################
#                                      BODY
################################################################################
# Make a temporary directory to store the source files in
echo "CREATING TEMPORARY DIRECTORY FOR SOURCE FILES"
mkdir ${TEMP_DIR}
cd ${TEMP_DIR}

echo "\n========================================================="
echo "DOWNLOADING THE SOURCE FILES"
echo "=========================================================\n"
wget -c ${CV_SOURCE_URL}

echo "\n========================================================="
echo "EXTRACTING THE SOURCE FILES"
echo "=========================================================\n"
unzip ${CV_SOURCE_PACKAGE} -d opencv_source_files
cd opencv_source_files/opencv*

echo "\n========================================================="
echo "BUILDING FROM SOURCE CODE"
echo "=========================================================\n"
# Create a directory to store the build
mkdir build
cd build

# A hacky variable used to sandwich comments in between a long line
COMMENT=

# Make the build
cmake \
    -D CMAKE_BUILD_TYPE=RELEASE           {COMMENT-"Release Mode "}\
    -D CMAKE_INSTALL_PREFIX=/usr/local    {COMMENT-"Installation path"}\
    -D INSTALL_C_EXAMPLES=OFF             {COMMENT-"No C examples"}\
    -D INSTALL_PYTHON_EXAMPLES=ON         {COMMENT-"Include Python Examples"}\
    -D BUILD_TESTS=OFF                    {COMMENT-"disable tests"}\
    -D BUILD_PERF_TESTS=OFF               {COMMENT-"disable tests"}\
    -D BUILD_EXAMPLES=OFF                 {COMMENT-"disable samples"}\
    -D WITH_TBB=ON    {COMMENT-"Enable Intel's (TBB) - For parallelization"}\
    -D WITH_EIGEN=ON {COMMENT-"Enable Eigen - for optimized math operations."}\
    ..

echo "\n========================================================="
echo "COMPILING FROM SOURCE CODE"
echo "=========================================================\n"
make -j${NCORES}  # compile using NCORES number of CPU cores

echo "\n========================================================="
echo "INSTALLING THE COMPILED BINARIES"
echo "=========================================================\n"
sudo make install
sudo ldconfig

################################################################################
#                       LINKING THE LIBRARY TO PYTHON
################################################################################
# All files are installed in the following directory:
#   /usr/local/

echo "\n========================================================="
echo "LINKING PYTHON to open CV"
echo "=========================================================\n"
# PYTHON 2.7
# For older versions of open cv, you may need to manually move the file
# to the correct place, using something like:
# cd /usr/lib/python2.7/dist-packages/
# sudo ln -s -f /usr/local/lib/python2.7/site-packages/cv2.so cv2.so

# PYTHON 3.4
# For older versions of open cv, you may need to manually move the file
# to the correct place, using something like:
# cd /usr/local/lib/python3.4/dist-packages/
# sudo ln -s -f /usr/local/lib/python3.4/site-packages/cv2.cpython-34m.so cv2.cpython-34m.so
#
# If that doesnt work,then try this one
# cd /usr/lib/python3/dist-packages
# sudo ln -s -f /usr/local/lib/python3.4/site-packages/cv2.cpython-34m.so cv2.cpython-34m.so

################################################################################
#                       REMOVING TEMPORARY INSTALLATION FILES
################################################################################
echo "\n========================================================="
echo "REMOVING TEMPORARY INSTALLATION FILES"
echo "=========================================================\n"
cd ${TEMP_DIR}
rm ${CV_SOURCE_PACKAGE}
rm -rf opencv_source_files

Credits

This tutorial is largely based on this Fedora tutorial but with the following modifications.

• Modified to work on ubuntu
• Updated for the specifics of opencv 3.3
• Modified to use packaged version zip files instead of the entire git repository.
• Modified to make use of multiple cores for the compilation of source code.
• Different compilation settings (eg, not disabling GPU support)
• Include discussion on how to use with virtualenv environments.