pyenv + pyenv-virtualenv + OpenCV 3 on Mac OS X El Capitan

Python is a good tool for quick project startup while it's still a little early to dig into the details of C++ or Objective C code.

The trouble is that the builtin Python version may not meet our needs. As you know, it starts to get messy when a couple of different versions of Python interpreters have been installed in the same OS. A few weeks later, you may find out things are not compiling properly due to all sorts of PYTHONPATH issues.

So, here comes the management tool - pyenv

Simply speaking, pyenv lets you easily switch between multiple versions of Python. On OS X, pyenv may install multiple versions of Python into its own repository location while the builtin version of Python is still intact with the OS. This minimises the conflict between your project and other existing applications which uses Mac's builtin Python for compiling work.

pyenv also comes with a plugin to deal with Python's virtual environment - pyenv-virtualenv 

pyenv-virtualenv provides features to manage virtualenvs and conda environments for Python.

With both of these, you can customise a particular version of Python as per Application based the virtual environment will trigger those changes for individual project folder.

To setup, please read through the README page via the following links:

https://github.com/yyuu/pyenv

https://github.com/yyuu/pyenv-virtualenv

To keep things simple, it is suggest that we should use homebrew to install above packages.

In the file ~/.bash_profile, typical setup is recommended as follows:

#
#
# Multi-Python switcher Pyenv
# To use Homebrew's directories rather than ~/.pyenv add to your profile:
export PYENV_ROOT=/usr/local/var/pyenv
export PATH="$PYENV_ROOT/bin:$PATH"
# Enable shims and autocompletion
if which pyenv > /dev/null; then eval "$(pyenv init -)"; fi

# A pyenv plugin to manage virtualenv (a.k.a. python-virtualenv) ref: https://github.com/yyuu/pyenv-virtualenv
# Automatically activate/deactivate virtualenvs on entering/leaving directories 
# which contain a .python-version file that lists a valid virtual environment
eval "$(pyenv virtualenv-init -)"
export PYENV_VIRTUALENV_DISABLE_PROMPT=1

# pip should only run if there is a virtualenv currently activated
export PIP_REQUIRE_VIRTUALENV=true
#
#
#
#

OpenCV is an excellent library for image/video processing. To avoid any error during the installation, it's recommended we install via homebrew command:

$
# First time installation
$ brew install opencv3 --HEAD --with-python3 --with-ffmpeg --with-tbb --with-contrib --with-opengl --with-qt5
# Upgrade alternative
$ brew reinstall opencv3 --HEAD --with-python3 --with-ffmpeg --with-tbb --with-contrib --with-opengl --with-qt5
$

All these will be done at global system level.

Now, using command like 'pyenv virtualenv' to setup a virtual environment for your project:

# Get into empty target project folder
$ mkdir ~/target_project
$ cd ~/target_project
$
# List available Python versions
$ pyenv versions
  system
  2.7.10
  2.7.12
  3.5.2
# Create new virtual environment with specific version
# Also name it 'my-env-3.5.2' or any other name
$ pyenv virtualenv 3.5.2 my-env-3.5.2
# Now activate new virtual environment within the target project folder
$ pyenv activate my-env-3.5.2
$

Assuming OpenCV 3 and Python 3.5.2 will be used within new virtual environment, it's time to link up OpenCV library folder to the target Python folder like /site-packages for importing reference.

# Assuming in ~/target_project folder
$ echo `brew --prefix opencv3`/lib/python3.5/site-packages >> $PYENV_ROOT/versions/my-env-3.5.2/lib/python3.5/site-packages/opencv3.pth
$

For Python virtual environment, we can setup necessary packages by using the following command within the target project folder

# Assuming in ~/target_project folder
$ 
$ pip install numpy
$

To test whether OpenCV 3 is supported within the virtual environment, let's open up Python console and import cv2 library:

# Assuming in ~/target_project folder
$ python
Python 3.5.2 (default, Jul 19 2016, 15:25:16) 
[GCC 4.2.1 Compatible Apple LLVM 7.3.0 (clang-703.0.31)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>import cv2
>>>

If no error is generated, we can ensure that OpenCV 3 library support is in place with current Python environment.