Installing and using Python

February 11, 2021 ยท View on GitHub

Migrating from Homebrew-installed Python

Note: Any virtualenvs that you have prior to this process will have to be recreated to use Python from pyenv.

Remove Homebrew-installed virtualenvwrapper

Before installing and configuring pyenv, uninstall virtualenvwrapper if it is installed via Homebrew:

brew uninstall virtualenvwrapper

Then remove the sourcing of virtualenvwrapper.sh and related variables from your shell's dotfiles (.profile, .bashrc for bash users, .zshrc for zsh users):

export VIRTUALENVWRAPPER_PYTHON=$HOME/homebrew/bin/python
export VIRTUALENVWRAPPER_VIRTUALENV=$HOME/homebrew/bin/virtualenv
source $HOME/homebrew/bin/virtualenvwrapper.sh

Optional: remove Homebrew-installed Python and variables

Before installing and configuring pyenv, it is a good idea to uninstall all old versions of Python and virtualenvwrapper that might be installed via Homebrew, and remove any varaibles from your shell's dotfiles (.profile, .bashrc for bash users, .zshrc for zsh users):

brew uninstall python
brew cleanup python
brew uninstall virtualenvwrapper

You should also remove any variables that reference Homebrew's Python from your shell's dotfiles (.profile, .bashrc for bash users, .zshrc for zsh users), for example, removing:

export PYTHONPATH=$HOME/homebrew/bin/python

If you do not wish to uninstall Homebrew's Python, or if you have Homebrew-installed packages that depend on Python-installed Homebrew, simply ensure that Homebrew's Python either does not exist in your shell's PATH variable, or that it is added to PATH before the pyenv configuration below.

Installing pyenv

To install pyenv on MacOS, use Homebrew:

brew update
brew install pyenv
brew install pyenv-virtualenvwrapper

Note: pyenv-virtualenvwrapper is not strictly required, depending on how you wish to manage your virtualenvs. See the notes in the pyenv-virtualewrapper README. Some of our documentation assumes virtualenvwrapper exists, so this guide installs it.

Configuring pyenv

Per the pyenv documentation, the follow environment variables need to be added to your shell dotfiles (.profile, .bashrc for bash users, .zshrc for zsh users).

# pyenv
export PYENV_ROOT="$HOME/.pyenv"

# pyenv-virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs

# Ensure this placed toward the end of the file
eval "$(pyenv init -)"

# Load virtualenvwrapper
pyenv virtualenvwrapper_lazy

Restart your shell.

Installing Python 2

Note: WARNING this version of Python is deprecated, but here's what to do if you're sure you need it.

We are still going to have internal projects (like the Intranet) that may require Python 2.7

pyenv install 2.7.16

Installing Python 3

We have projects that require Python 3.6

pyenv install 3.6.9

Before you can use a version of Python, you have to set them as either global or local versions.

Setting the global Python 2 version

By default with pyenv when you invoke python, you will be using the system-installed Python. To set the global Python version to 2.7.16:

pyenv global 2.7.16

This will make python version 2.7.16. This is NOT our recommended configuration.

Setting the global Python 3 version

By default with pyenv when you invoke python, you will be using the system-installed Python. To set the global Python version to 3.6.9:

pyenv global 3.6.9

This will make python version 3.6.9. This is our recommended configuration.

Using local Python 2 version

pyenv also allows you to set a local Python version (the version of Python that is available in the current directory):

pyenv local 2.7.16

Using local Python 3 version

pyenv also allows you to set a local Python version (the version of Python that is available in the current directory):

pyenv local 3.6.9

This will create a .python-version file in the current directory. When you're in that directory or below it, pyenv will use the version you've specified here as python.

Note: Please ensure that .python-version is in the .gitignore file for a given repository and that it does not get committed.

Note: When you create a virtualenv with mkvirtualenv with a local Python version set, it will default to that local Python version, and not the global version. You can still specify -p argument with the specific Python you wish to use.

Upgrading Python versions

To change the local Python version to the new version, for example, 3.7.2, follow the same approach you took to setting it the first time:

pyenv local 3.7.2

And the local .python-version file will contain 3.7.2.

This does not work for virtualenvs, however. If you install a new version of Python, for example, 3.7.2, you must recreate the virtualenv with the new version of Python. The virtualenv will have be recreated (mkvirtualenv) with the new version of Python either set locally, globally, or specified with --python:

If you already have created a virtual environment in the past (and it's running):

deactivate
rmvirtualenv consumerfinance.gov

If Python 3.6 is already set up as the local Python (which it should be if you followed steps above, check by running pyenv versions):

mkvirtualenv consumerfinance.gov

If Python 3.6 isn't set as the local Python, you need to specify when you create the virtual environment:

mkvirtualenv --python=python3.6 [virtualenv name]

Further reading

Virtualenv and its alternatives: