If you are working with python or any other programming language, you usually face the versioning problem. Say you might need to run legacy project that has been written by python 2, then you would have to switch to project that being written in python 3.9, or the newest python version got released and you want to try its new functionalities.

So this guide will help you maintain and activate the proper python version that can facilitate your development with pyenv.

Install pyenv

At a high level, pyenv intercepts Python commands using shim executables injected into your PATH, determines which Python version has been specified by your application, and passes your commands along to the correct Python installation.

This guide will not dive deep into the mechanism of how it works and manage python version in the background, but to focus on how to install, what command we need to remember and workflow when working with multiple projects.

To install for MacOS, the easiest way is to use homebrew

$ brew update
$ brew install pyenv

If you use other operating system, please run this

$ curl https://pyenv.run | bash

After the installation process, run eval "$(pyenv init -)" to install pyenv into your shell as a shell function, enable shims and autocompletion.

Setup shell

It really depends on which shell you are using to append the equivalent snippet. The snippet below if for zsh:

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
$ echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
$ echo 'eval "$(pyenv init -)"' >> ~/.zshrc

If you are using fish, or bash, please copy the corresponding snippet here.

After that, please restart your shell to take effect:

$ exec "$SHELL"

Install your desire python version

Install python build dependencies

Build dependencies are used when you install and compile python, so make sure to install them in your system before process to install the dependencies.

For MacOS, run:

$ brew install openssl readline sqlite3 xz zlib tcl-tk

If you use any other Linux distros, please install the equivalent dependencies as described here

Install python specific version

First, see the available version of python through pyenv

➜ pyenv install -l
Available versions:
  2.1.3
  2.2.3
  2.3.7
  2.4.0
  2.4.1
  ...
  3.11.0
  3.11-dev
  3.11.1
  3.11.2
  3.11.3
  3.12.0a7
  3.12-dev

Install the version you want by running: pyenv install <version>

$ pyenv install 3.11.3

You can install as many as you want, after install, we can activate which one to be in used by the system in the next step

Activate python to use

You can use pyenv versions to view the available python versions in your system, then you can use one of the following commands:

  • pyenv shell <version>: select just for current shell session
  • pyenv local <version>: automatically select whenever you are in the current directory (or its subdirectories)
  • pyenv global <version>: select globally for your user account

Example, when I want to work with python 3.11.3, I usually just run:

$ pyenv global 3.11.3

When you want to use the system python instead, use system as version name:

$ pyenv global system

To install python 2 on Apple Silicon chip, you should install the version 2.7.18 (according to the doc).

To have python 3 and python 2 coexist, while python will evaluate to python 3 version, and python2 will be evaluated to python2 version, you can run this:

$ pyenv global 3.11.7 2.7.18

Troubleshooting

Check if pyenv is recognized by the system

$ which pyenv

Check if shims is added to the PATH

$ echo $PATH | grep --color=auto "$(pyenv root)/shims"

Conclusion

With pyenv set up, you can now easily switch python version for your projects. Python and pip will work flawlessly, you can also configure the virtual environment to manage dependencies further.