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
- installing Homebrew,
- installing
pyenvusing Homebrew, and - 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.
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.
Homebrew is an excellent package manager for macOS. Having it will be helpful for installing many things beyond just Python.
- 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- 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)"- 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 updateRead more details about installing Homebrew here.
I like using pyenv to manage multiple Python versions, as it sticks to the Unix philosophy of doing one thing well.
- First, install its appropriate Python build dependencies with
brew install openssl readline sqlite3 xz zlib- Then, install
pyenvwith
brew install pyenvFinally, 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.
- Find out which shell you're using with
echo $0In macOS you should get either bash or zsh; see screenshot below.
- 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.
pyenv allows us to install many different Python versions. You can check out the full list of available versions by running
pyenv install --listYou'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 exampleIf 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.
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.13I can check that this worked by running pyenv version again, or simply by initializing the Python REPL with python. See output below.
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,
- 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.
- https://opensource.com/article/19/6/python-virtual-environments-mac
- https://www.freecodecamp.org/news/python-version-on-mac-update/
- https://stackoverflow.com/questions/29687140/install-latest-python-version-with-pyenv
- https://stackoverflow.com/questions/41573587/what-is-the-difference-between-venv-pyvenv-pyenv-virtualenv-virtualenvwrappe