If you are a developer working with python, you should be using VirtualEnv to manage requirements for your projects and Virtualenwrapper to make your life easier with useful shortcuts.

Virtualenvwrapper has a very good documentation and python installation with Homebrew is straightforward, but It’s incredible to see that on every developer’s computer I help, I find several issues with their installation. So the motivation of this blog post is to provide a definitive guide to configure your python installation in a way that prevents future problems in OSX.

Since we are in 2018 (or after), I also suppose that all your current projects work with python3, right? So this guide will be completely different to anything you read everywhere. If most of of your projects are python2 and you have a few in python3, please go somewhere else.

I know, It’s not your fault, OSX Mojave still comes with python 2 by default 🙁  but It shouldn’t have anything to do with your development setup, because you shouldn’t be using the system libraries for development… Leave the system alone.

Don’t even try to remove or update the default python2 that comes with the operative system! Things like sudo something are forbidden if you don’t want break things. You are not in Windows, so you shouldn’t need to modify your system to configure your development environment.

Python3 installation

I will assume you just have a fresh copy of your operative system (you haven’t screwed it up!), you already have installed Homebrew to manage your system dependencies and you use zsh as your shell.

Let’s have everything up to date and check that system is OK before we start:

brew update && brew upgrade
brew doctor

You should read something like:

brew doctor
Your system is ready to brew.

If you get warnings, I recommend you fix them before continuing with anything else. If you don’t have Homebrew configured the right way, your life could be complicated in the next steps.

Since everything is fine, it’s time to install python3:

brew install python

It will install python3 by default, and you will get a confirmation like this:

Python has been installed as
  /usr/local/bin/python3

Unversioned symlinks `python`, `python-config`, `pip` etc. pointing to
`python3`, `python3-config`, `pip3` etc., respectively, have been installed into
  /usr/local/opt/python/libexec/bin

If you need Homebrew's Python 2.7 run
  brew install python@2

You can install Python packages with
  pip3 install <package>
They will install into the site-package directory
  /usr/local/lib/python3.7/site-packages

See: https://docs.brew.sh/Homebrew-and-Python
==> Summary
/usr/local/Cellar/python/3.7.1: 3,824 files, 59.2MB

In this moment, you have installed python3, but It’s still not the default python in your environment, if you type in python -V, you will still get python 2.7, and you will only get python3 if you explicitly run python3.

python -V
Python 2.7.10

python3 -V
Python 3.7.1

You could keep running python3 for everything when required, but It makes things more complicated in future virtualenvwrapper configuration, so we are going to set python3 as the default version of python to use on my user. To do so we are going to modify the PATH with the following instruction:

export PATH="/usr/local/opt/python/libexec/bin:/usr/local/sbin:$PATH"

With this instruction, you have set precedence to your python3 installation over the default python installation, and you can verify it by running:

python -V
Python 3.7.1
pip -V
pip 18.1 from /usr/local/lib/python3.7/site-packages/pip (python 3.7)

To make it permanent edit the .zshrc file:

echo 'export PATH="/usr/local/opt/python/libexec/bin:/usr/local/sbin:$PATH"' >> ~/.zshrc

Virtualenvwrapper installation and configuration

Having this configured, the virtualenvwrapper installation will be much easier, and just as explained in the installation guide

pip install virtualenv
pip install virtualenvwrapper

Now add it to shell startup file (.zshrc):

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

Now you will have virtualenvwrapper ready, so you can create virtual environments for your python projects by just running mkvirtualenv ENVIRONMENT and switch to a specific virtual environment by using workon ENVIRONMENT. You can read more about how to use virtualenvwrapper on the official documentation.

Bonus track: Python2

Do you need to work a project with python2?… OK, It’s not the end of the world. Guido van Rossum may forgive you.

The following lines are self explanatory. Install python2 and when you need to use python2, set it explicitly:

brew install python2
mkvirtualenv py2 -p python2

Happy coding!