In a nutshell

  • Homebrew installs libraries to /usr/local/Cellar/
  • brew install opencv creates /usr/local/Cellar/opencv/
  • brew install opencv3 creates /usr/local/Cellar/opencv3/
  • Both the above libraries contain a Python module, stored at a path similar (but not necessarily identical) to:
  • Homebrew Python imports that module via a symlink at:
  • Create another subdirectory inside site-packages, for example, /opencv3 and put a symlink to the 3.x.x file in there:

$ ln -s /usr/local/Cellar/opencv3/3.x.x/lib/python2.7/site-packages/ \
  • If you want to import the 3.x.x version, add the following line at the top of your script to temporarily add the new site-packages subdirectory to the PYTHONPATH:

>> import sys
>> sys.path.insert(0, 'usr/local/lib/python2.7/site-packages/opencv3')
>> import cv2
>> print cv2.__version__

In more detail

Recently I’ve been working on a project that’s written in Python/OpenCV/Caffe.

After spending a while installing Caffe on OS X, I was pretty disappointed to find out that my friend and I were actually working from different versions of OpenCV, and as a result the simple application wrapper written in Python-OpenCV was crashing even though everything Caffe was just fine. Like a lot of people, I’ve got a system-wide install of 2.4.X, which I use for just about everything. Meanwhile he was feeling terrifically trendy and had installed OpenCV version 3.

Here’s how I solved the problem, installing OpenCV 3.1.0 side-by-side on my system with version 2.4.12 so that I can choose which one to use from Python. It’s not pretty, it’s not necessarily advisable, but it works.

N.B: This won’t work for everyone. It should work for homebrew users like myself. Here I’ll refer to Python 2.7, although you could of course do this for other versions by adding flags to the homebrew installation of OpenCV.

Check that you’re using a Homebrew Python install by confirming that the following command produces the following output:

$ which python

Next up, confirm where your current OpenCV version is installed. I installed 2.4.12 with Homebrew (brew install opencv) so it’s found at:


And inside that directory you’ll find the Python module:

<above path>/lib/python2.7/site-packages/

That .so file is what you’ve been using every time you’ve written import cv2. Take a peek inside /usr/local/lib/python2.7/site-packages and you’ll find an alias/symlink to the very same file. So Python imports the module from inside the Homebrew Cellar via a symlink in your Python’s site-packages.

Now we’re going to try and stick OpenCV 3 right in there alongside it. That means installing the library into the Homebrew cellar, and setting up a symlink to the Python module from our Python’s site-packages.

Installing OpenCV 3

This is really easy these days, you can brew it just like you did with opencv back in the day:

$ brew install opencv3

At this point, you should be able to find your new library at:


And you’ll probably be able to find a new inside /usr/local/lib/python2.7/site-packages alongside the existing one.

Picking a version from Python

We obviously can’t have two aliases in the same directory both called, but it turns out we also can’t just rename the new one without Python getting upset about _init_ methods and such. My solution was to create a directory opencv3 and put the new alias to 3.x.x in there, so that the Python site-packages directory now contains both the old alias and now opencv3/ too.

Python won’t find the cv3/ link unless you explicitly tell it to search for modules in that directory, so by default import cv2 will give you your old version:

>> import cv2
>> print cv2.__version__

But you can force Python to search there (and search their first) with:

>> import sys
>> sys.path.insert(0, 'usr/local/lib/python2.7/site-packages/opencv3')
>> import cv2
>> print cv2.__version__

Et voila. Multiple OpenCV versions installed system-wide, with the option to choose between them from Python. Whether this is a good idea is completely besides the point.