Definitive guide to python on Mac OSX

You should setup python on your Mac this way. I’m tired of having to look this up, or worse, describe it ineffectively to coworkers. So here it is, all in one place.

Why this way?

You have python on your Mac, can’t you use the built-in python? Isn’t any other method just for experts?


Here are the problems with using the built-in python:

  • Installed PyPi packages pollute your system python, potentially causing system problems
  • OpenSSL used by the system python is old and vulnerable. Old as in, doesn’t understand websites that require TLS 1.1 or later
  • You’re stuck with whatever python 2.7 version comes pre-installed, and no python 3.x
  • Many other reasons, lets move on

NOTE: If you are using python for scientific computing, statistical analysis, machine learning, or you frequently experience the terms ‘numpy’, ‘scipy’, or ‘MATLAB’ in your daily life, you might benefit from using Anaconda instead of the method described here. If you have no idea what I’m talking about, please read on.

Install Xcode

Xcode is required to install Homebrew and Python. Download it from the App Store.

Install Xcode from the App Store

After a lengthy download and install process, open a terminal and type the following command to install Xcode Command Line tools which are required for Homebrew:

xcode-select —-install

Install Homebrew

Homebrew is a package manager for OSX. We’ll use it to install specific versions of python that coexist with, and prevent pollution of, the system python.

Go here:

Follow the directions to install Homebrew, which at the time of this writing is to paste this line into a terminal:

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

Install Python

Now that Homebrew is installed, use it to install python. The OSX system will still use the built-in system python, but anything you do will use the newly installed python.

Install latest python 2.7:

brew install python

Install latest python 3.x

brew install python3

You have python! Done, right?? Nope.

Install virtualenv and virtualenvwrapper

Virtualenv is short for “Virtual Environment”. It’s like a sandbox where you can install python packages that won’t pollute the global python. That’s right, we installed python so we wouldn’t pollute the system python. Now we install virtualenv so we don’t pollute our shiny new python install.

Virtualenvwrapper is a set of friendly commands that help us work with the otherwise obtuse virtualenv. It’s optional, but lightweight and very useful.

Use pip to install virtualenv and virtualenvwrapper in your new python.

pip install virtualenv
pip install virtualenvwrapper

NOTE: if you did NOT install python 2.7 in the previous step, then use pip3 instead of pip in this step. If you installed python 2.7 (with or without python 3.x), then use pip.

Also upgrade pip while you’re here:

# python 2.7
pip install -U pip
# python 3.x
pip3 install -U pip3

Now we’ll add a few important pieces to the terminal environment. Add the following lines to the file .bash_profile in your home directory. Create that file if it doesn’t exist:

Save the file, then close and re-open your terminal window to activate the changes.

You have now activated virtualenvwrapper, and locked down pip to only work inside a virtual environment so you can’t accidentally install python packages to the global python environment. Don’t worry, if you still want to install a python package globally (you don’t!) you can use gpip or gpip3 to override this protection and force a package to install globally.

Go forth!

You’re now ready to work with python. Create a virtual environment to work in first:

# python 2.7
mkvirtualenv myproject
# python 3.x
mkvirtualenv -p python3 myproject

You should see the name of your virtual environment in the prompt indicating it is safe to install package with pip:

(myproject) computer1:~$

Install any packages you need for your project. This example installs the requests package:

# python 2.7
pip install requests
# python 3.x
pip3 install requests

You can exit the virtual environment easily by typing:


Or return to it later with:

workon myproject

And finally, remove all trace of the many packages you’ve installed in the virtual environment with the command:

rmvirtualenv myproject


Further reading on virtualenvwrapper commands: