My Python setup (OSX)

python-setup.md

My Python setup (OSX)

Lots of people (myself included) have been confused about how to go about installing Python on a new (or old) machine. This document is an attempt to maintain an up-to-date, succint guide on how to properly set up Python on macOS. It's 2021, so we'll focus on Python 3 here ffs.

The process is simple. Broadly speaking, my method boils down to

1. installing Homebrew,
2. installing pyenv using Homebrew, and
3. installing one (or more) Python version(s) using pyenv

Yes, there are many more ways of doing this. Here we'll focus on my way, which is nevertheless based on careful testing and assesment of pros and cons of each method. See here or here for more details on available alternatives.

Who is this for

This guide is for someone who wants a modern Python setup where one can easily manage multiple versions and project-specific virtual environments. If you're unsure at which side of the chessboard you are, I'd still recommend following this guide until you set up a global pyenv Python version. Even if you only use one environment, it will still be easier to maintain if you control it with pyenv (as opposed to running the official Python installer, for instance). It will also future-proof your setup in the case that later down the road you need to manage multiple versions and environments.

Installing Homebrew

Homebrew is an excellent package manager for macOS. Having it will be helpful for installing many things beyond just Python.

1. First you'll need Xcode. If you won't be using Xcode for anything else, you can install a minimal version using

xcode-select --install

2. Homebrew's homepage has the latest install instructions, which should boil down to running the following line:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. I suggest that right after installing Homebrew, you make sure all package definitions (a.k.a. formulae) are up-to-date, which can be done with

brew update

Read more details about installing Homebrew here.

Installing pyenv

I like using pyenv to manage multiple Python versions, as it sticks to the Unix philosophy of doing one thing well.

1. First, install its appropriate Python build dependencies with

brew install openssl readline sqlite3 xz zlib

2. Then, install pyenv with

brew install pyenv

Finally, you need to add pyenv to your path so that it runs the appropriate version of Python when using the shell (more details here in step 2 here). The instructions to correctly set up pyenv depend on which shell you're using.

3. Find out which shell you're using with

echo $0

In macOS you should get either bash or zsh; see screenshot below.

4. Follow the instructions from in step 2 here. Basically, if your shell is
   • bash, then run

   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
   echo 'eval "$(pyenv init --path)"' >> ~/.profile
   echo 'if [ -n "$PS1" -a -n "$BASH_VERSION" ]; then source ~/.bashrc; fi' >> ~/.profile
   echo 'eval "$(pyenv init -)"' >> ~/.bashrc

   • zsh, then run

   echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
   echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Adding these line ensures that every new shell instance will initiate pyenv to manage the PATH environment variable, inserting the version of Python we want to run. Read more details about installing pyenv in its readme.

Installing Python with pyenv

pyenv allows us to install many different Python versions. You can check out the full list of available versions by running

pyenv install --list

You'll get a long list of options. If you know which specific version you recquire (say, for a pre-existing project), you can install a specific version with pyenv install <version>. For example,

pyenv install 3.8.12    # just an example

If you are unsure about which version to install, I'd recommend to install the latest one. The latest available version can be printed out and installed using the following commands:

# print latest version:
pyenv install --list | sed 's/^  //' | grep '^\d' | grep --invert-match 'dev\|a\|b' | tail -1
# install latest version:
pyenv install $(pyenv install --list | sed 's/^  //' | grep '^\d' | grep --invert-match 'dev\|a\|b' | tail -1)

Keep in mind that you can always add or remove versions, so this decision is not critical. To uninstall a version, simply use pyenv uninstall <version>. See here for more info.

Set up global Python default

Now that Python 3 is installed via pyenv, we need to set it as a global (i.e. system default) version. You can check out the available Python versions in your machine with

pyenv versions

The output I get after running this command in my local machine is above. Notice that there is an asterisk next to 3.8.6: this indicates it's the active version, which in this case, it's the one I've set up as my global Python version. This can also be obtained by running pyenv version (singular).

We can change the global default version by running pyenv global <version>, where <version> is any of the ones listed when running pyenv versions. For example, I can switch my global default version to 3.6.13 by running

pyenv global 3.6.13

I can check that this worked by running pyenv version again, or simply by initializing the Python REPL with python. See output below.

Understanding the modern Python setup

This is completely optional, but probably worth knowing. The pyramid below depicts the resolution order for which Python gets used when you call python in your terminal.

From bottom to top,

1. System Python is the one that comes bundled with macOS, and likely to be version 2.7.something. You never wnat to use or touch or remove System Python.

References

1. https://opensource.com/article/19/6/python-virtual-environments-mac
2. https://www.freecodecamp.org/news/python-version-on-mac-update/
3. https://stackoverflow.com/questions/29687140/install-latest-python-version-with-pyenv
4. https://stackoverflow.com/questions/41573587/what-is-the-difference-between-venv-pyvenv-pyenv-virtualenv-virtualenvwrappe