Homebrew

For a long time, I managed all my Python installations with homebrew. If you’re not familiar with it, homebrew is a package manager that lets you installed tools on the command line, similar to what you get from aptitude or yum on Ubuntu or Fedora respectively.³ If you’re not using homebrew yet, I highly recommend it for installing command-line tools. (If you’re not using command-line tools yet, then the rest of this post will either bore you to death, or prove extremely enlightening!) If you haven’t started yet, now’s a good time: go install it!.

While homebrew is great for installing and managing packages in general, I can’t say this loud enough: don’t manage Python with homebrew. It’s finicky, and really isn’t meant for all the things you have to do to manage more than one version of Python at a time.⁴ (There’s a reason there’s a whole troubleshooting section devoted to it.) If you think it’s crazy that I might want more than one copy of Python installed a time, well… let’s just say I suspect you’ll change your mind after doing a bit more development. (At the most basic, most people will end up wanting both Python 2 and 3 installed, and will want to upgrade them as bug fixes and the like come out.)

pyenv

Instead of installing via homebrew, use it to install pyenv, and use that to manage your installations. pyenv is a dedicated tool for managing your “Python environment,” and it excels at that. If you were on a Mac with homebrew installed, your setup process to add the latest version of Python might look something like this:

$ brew install pyenv
$ echo 'eval "$(pyenv init -)"' >> ~.profile
$ source ~/.profile
$ pyenv install 3.4.3

Line by line, that (a) installs pyenv, (b) adds a hook to your shell profile,⁵ (c) updates your current session using the updated profile, and (d) installs the latest version of Python (as of the time I’m writing this). Now you have a full version of Python 3.4.3 alongside the system install of Python 2.7.6. If you wanted to install 2.7.9, or 2.2.3, or the development version of PyPy3, you could easily do that as well.

In addition, pyenv lets you specify which version to use globally (pyenv global <name>) and which version to use in a given directory structure (pyenv local <name>). So if you prefer to use Python 3 in general, but need to use Python 2 on one project, you can just navigate to the root of that project and set it:

$ pyenv global 3.4.3
$ cd path/to/my/project
$ pyenv local 2.7.9

This will create a simple plain text file, .python-version, whose contents will be just 2.7.9—but for everything under path/to/my/project, typing python will launch Python 2.7.9, while typing it outside that folder will launch Python 3.4.3. (If you want, you can just create the .python-version file yourself manually and give it the name of a version. There’s nothing special about it all; it’s just the place pyenv looks to know which Python version to use.)

venv and virtualenv

If you have Python 3.3 or later, you have a built-in tool for this called pyvenv; if you have Python 3.4 or later, it supports pip right out of the gate so you don’t have to install it yourself. If you’re on older versions, you can install virtualenv (pip install virtualenv) and get the same basic tooling: pyvenv was inspired by virtualenv. Then you can create virtual environments with the pyvenv or virtualenv commands, and use those to isolate different setups from each other. If you haven’t started using virtual environments yet, start now!

pyenv with virtualenv

I know, the similarity of names for pyenv and pyvenv is unfortunate. If it helps, you can call the latter as venv rather than pyvenv. But, more importantly, one of the areas pyenv is much better than homebrew is its support for managing virtual environments. Install pyenv-virtualenv:

$ brew install pyenv-virtualenv
$ echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.profile

Now you’re off to the races: you’ll never have to type pyvenv <path to a virtual environment>, because instead you can just type pyenv virtualenv <version> <name> and pyenv will take care of setting it up for you. Even better: all the nice tricks I listed above about setting directory-specific and global preferences for which Python version to use work equally well with virtual environments managed via pyenv. In other words, you can do something like this:

$ pyenv install 2.7.9
$ pyenv install 3.4.3
$ pyenv global 3.4.3
$ pyenv virtualenv 2.7.9 my-virtual-environment
$ cd path/to/my/project
$ pyenv local my-virtual-environment

The .python-version file will contain my-virtual-environment. The Python version will be 2.7.9. The environment will be isolated, just as if you had run pyvenv to set up a virtual environment. Everything works together beautifully! Moreover, you can easily reuse virtual environments this way, because you can set the local value in more than one place. For example, I use the same virtual environment for this site and Winning Slowly, because they have slightly different site configurations but all the same Python dependencies. Creating it was simple:

$ pyenv install 3.4.3
$ pyenv virtualenv 3.4.3 pelican
$ cd ~/Sites/chriskrycho.com
$ pyenv local pelican
$ cd ~/Sites/winningslowly.org
$ pyenv local pelican

I named the virtual environment after the tool I use to generate the sites, and reused it in both sites. Both now have a .python-version file that reads pelican. Now, anytime I’m working anywhere under ~/Sites/chriskrycho.com or ~/Sites/winningslowly.org, I have the same tooling in place.