Set Up Python Development Environment on Mac OS X (macOS)

To set up a clean and easy to manage Python development environment on Mac OS X (or more generally - a Linux-like working environment), I try to obey the following guidelines:

  • Use Homebrew as the package management tool. General tools or system wide packages are installed through Homebrew.

  • Install Python 2 and 3 (including pip) from Homebrew. Though Python 2 comes with OS X by default, but the version might be lower and may be changed due to OS X upgrade in the future. So it is better to avoid to use this python version.

  • Install virtualenv through pip. Create a virtual environment for each project, and install corresponding packages to that virtual environment.

For any python package that I am going to use in my Python project, I try to install that from pip first. If it can not be found or installed for some reasons, I then try to install from Homebrew or source.

Install Homebrew

Homebrew, as specified as the “The missing package manager for macOS” on its official website, is a truly fantastic software to help Mac users to install and manage various packages as easy as like on a Linux system. To install Homebrew, simply copy the following command to a shell:

/usr/bin/ruby -e "$(curl -fsSL"

Install a package through Homebrew is quite straightforward. For example, the following command will install git from Homebrew’s collection:

brew install git

Another wonderful thing of Homebrew is that it installs packages to their own directories and then symlinks their files to /usr/local. As a result, the git package is installed under /usr/local/Cellar/git and a symlink binary of git is created under /usr/local/bin. The /usr/local/bin should be pretended to the PATH environment by Homebrew so that our custom installed program will come before the default system version. In case of this directory is not in the PATH, put the following command in to .bash_profile and then source .bash_profile:

export PATH=/usr/local/bin:$PATH

Install Python and Virtualenv

To install Python through Homebrew:

brew install python

It installs pip, setuptools and wheel as well. If I need to install some general Python packages, e.g. autopep8 for Emacs Python mode, I do the following:

pip install autopep8

pip will install the package to the /usr/local/lib/python2.7/site-packages directory of our Homevrew version of Python.

To install virtualenv, I follow instruction from The Hitchhiker’s Guide to Python. I create a virtualenv called PyStation for my general purpose numerical simulation.

mkvirtualenv PyStation

To change to that virtual environment:

workon PyStation

Now if check which python and which pip, I get following results:


To install some common numeric and scientific Python packages:

pip install numpy, matplotlib, scipy

These packages will be installed to the site-packages of the Python in this virtual environment, i.e.


Special case for PyQt and OpenCV

For some reason I can not install PyQt through pip, so I has to install PyQt and Qt from Homebrew.

brew install Qt, PyQt

These two packages will be installed into their directories under the Homebrew Cellar directory, but some symlinks for PyQt4 are created for the Homebrew Python as well under the /usr/local/lib/python2.7/site-packages directory. This means that we can use PyQt within the environment of Homebrew Python version. In order to use PyQt in my PyStation virtualenv, I have to create the same symlinks for PyQt under that Python’s site-packages directory.

cd /Users/xiaok/VirtualEnvs/PyStation/lib/python2.7/site-packages
ln -s /usr/local/lib/python2.7/site-packages/PyQt4/ PyQt4
ln -s /usr/local/lib/python2.7/site-packages/
ln -s /usr/local/lib/python2.7/site-packages/

To use OpenCV in the virtual environment, first install OpenCV from Homebrew:

brew install opencv

Then create symlinks for OpenCV as well:

cd /Users/xiaok/VirtualEnvs/PyStation/lib/python2.7/site-packages
ln -s /usr/local/lib/python2.7/site-packages/
ln -s /usr/local/lib/python2.7/site-packages/