Oct 14 2014 Installing OpenCV in a virtualenv on Ubuntu and OSX

$ pip install opencv never seems to work quite right. If you get the message

Could not find any downloads that satisfy the requirement opencv
Cleaning up...
No distributions at all found for opencv

There are a handful of answers strewn across the internet about installing OpenCV's Python bindings, but none of them seem to apply to installing them in a virtualenv in Linux. In the interest of collecting all that information in one place, here's what I did to get it running. I'm using:

• Ubuntu 14.04 64 bit
• Python 2.7.6
• OpenCV 2.4.9.0

Update: You may find luck using opencv-python, an unofficial package of the python bindings for OpenCV. If you only need to use the Python interface, you can just pip install opencv-python and should be good to go.

This will install OpenCV, the Python bindings, and Numpy system-wide, but afterward you will be able to use them inside a virtualenv. This assumes you have pip, virtualenv, and virtualenvwrapper installed and properly configured. If you aren't familiar with these, Googling yields many resources, for example this tutorial.

First, install OpenCV's dependencies, per the installation instructions. (Some of these were pre-installed on my system)

$ sudo apt-get install build-essential cmake libgtk2.0-dev pkg-config \
python-dev libavcodec-dev libavformat-dev libswscale-dev{% endhighlight %}

The next part had me tripped up for a little bit. OpenCV doesn't play particularly well with virtualenvs, so numpy needs to be installed on the system Python:

$ sudo pip install numpy

After that, continue to build OpenCV per the instructions. Download the source (I'm using version 2.4.9.0, from here and unzip it in the directory of your choice.

$ unzip opencv-2.4.9.zip
$ cd opencv-2.4.9
$ mkdir build
$ cd build

Configure the make files using cmake. There is a flag required for the Python bindings that I couldn't find in the official documentation, only in StackOverflow questions: BUILD_NEW_PYTHON_SUPPORT. Also note the two trailing periods.

$ cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local \
-D BUILD_NEW_PYTHON_SUPPORT=ON ..

This will output a lot of text, but if you scroll up you should find a section referring to Python. It will refer to the system Python binary. This is fine. We will set up our virtualenv later.

After the build is configured, time to make the project. This will take a few minutes to run.

$ make
$ sudo make install

After the build completes, you need to set up your virutalenv if you haven't already. Numpy also needs to be installed in the virtualenv.

$ mkvirutalenv opencv
[...]
(opencv) $ pip install numpy

Now that our virtualenv is ready to go, we just need to copy the OpenCV binary into the virtualenv's site-packages directory. It should be somewhere under the location you installed it, mine was in /usr/local/lib/python2.7/dist-packages/cv2.so

(opencv) $ cd lib
(opencv) $ cp /usr/local/lib/python2.7/dist-packages/cv2.so ~/.virtualenvs/opencv/lib/python2.7/site-packages

You can now delete the opencv-2.4.9 directory if you want. The reason we don't want the cv2.so that got built there is the libraries it's linked to. If you run $ ldd cv2.so you'll get something like

libpython2.7.so.1.0 => /usr/lib/x86_64-linux-gnu/libpython2.7.so.1.0 (0x00007fe78eca2000)
libopencv_core.so.2.4 (0x00007fe78e7f9000)
libopencv_flann.so.2.4 (0x00007fe78e585000)
libopencv_imgproc.so.2.4 (0x00007fe78e096000)
(...)

See that first one with an absolute path (/usr/lib/...)? The other ones are linked to copies in the build directory so if you delete them, cv2.so won't have its full feature set, even though it may import correctly.

$ ldd /usr/local/lib/python2.7/dist-packages/cv2.so
libpython2.7.so.1.0 => /usr/lib/x86_64-linux-gnu/libpython2.7.so.1.0 (0x00007f9f27e63000)
libopencv_core.so.2.4 => /usr/local/lib/libopencv_core.so.2.4 (0x00007f9f279bb000)
libopencv_flann.so.2.4 => /usr/local/lib/libopencv_flann.so.2.4 (0x00007f9f27746000)
libopencv_imgproc.so.2.4 => /usr/local/lib/libopencv_imgproc.so.2.4 (0x00007f9f27257000)
libopencv_highgui.so.2.4 => /usr/local/lib/libopencv_highgui.so.2.4 (0x00007f9f26e1e000)
(...)

Ahh, much better.

Everything should be good to go:

(opencv) $ python
>>> import cv2
>>>{% endhighlight %}

If you get ImportError: no module named cv2 double check you had the BUILD_NEW_PYTHON_SUPPORT flag set, and that numpy is installed for the system Python. If you get the error message ImportError: numpy.core.multiarray failed to import you need to install numpy in your virtualenv. From inside the virtualenv, (opencv) $ pip install numpy should fix that. I believe that should do the trick.

Update June 14, 2017:

OSX troubleshooting

These tips from a reader may help you troubleshoot errors on OSX Sierra.

If you get Error compiling OpenCV, fatal error: stdlib.h, try adding the cmake flag -DENABLE_PRECOMPILED_HEADERS=OFF

cc1plus: some warnings being treated as errors -Wno-error

error: "if (&annotate_img!=NULL)

This issue has been fixed as of OpenCV version 2.4.13, try upgrading to the latest version of OpenCV 2 or 3.

Good luck with your computer vision!