If you want to write Python code on macOS and you are a newbie developer, the easiest way is to use the out-of-the box Python that comes shipped with macOS. However, you will quickly experience the downsides of this. Just assume you are on two projects using different Python versions. It is very likely that you projects have conflicting dependencies. What you need is a way to use multiple Python versions in parallel with easy switching between them. This is wehere pyenv comes into play.
pyenv manages multiple Python environments providing easy means for switching environments and installing new versions. There are different ways of installing pyenv on macOS. The quickest and easiest way is via Homebrew. If Homebrew is not net installed on your system, just take quick detour to the post on Installing Homebrew on MacOS.
Installing pyenv
You can install pyenv with the following steps. Please note that there is a slight difference whether you are using bash or Zsh as your shell. If you are note sure which one you have, open your terminal and enter
$ echo $0
This should return either
-bash
or
-zsh
Which shell you use makes a difference for which shell startup script to use.
Installing Homebrew if necessary
Install Homebrew if it is not available. To find out if it is installed, run the command.
$ brew update
This might fail with the message
command not found: brew
If this is the case you need to install Homebrew first according to Installing Homebrew on MacOS.
If Homebrew is installed, it might run some updates and provide output or you might see
Already up-to-date.
In these two cases Homebrew is already up and running and we can go on.
Installing pyenv
You can simply install pyenv with
$ brew install pyenv
If this concludes without an error, congratulations! You just installed pyenv. In the next step, you need to tell your terminal to prefer the Python versions installed via pyenv over the system version. Here it makes a difference which shell you use.
Bash
# Add pyenv initializer to shell startup script
$ echo 'eval "$(pyenv init -)"' >> ~/.bashrc
# Reload your profile
$ source ~/.bashrc
Zsh
# Add pyenv initializer to shell startup script
$ echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# Reload your profile
$ source ~/.zshrc
Cool! pyenv is installed and everything should properly loaded when you open the terminal. Now it is time to install some versions of Python and choose which one to use.
Installing and handling multiple Python versions
pyenv offers a wide range of commands but here are the ones you will use most of the time. At first, we want to know which versions of Python are available.
$ pyenv install --list
This command prints a long list of all Python versions and distributions that are available to pyenv. If you find a suitable version — for example 3.9.1 — you can install it with the command
$ pyenv install 3.9.1
After the installation completes, the version is available to use. You can repeat that for every version you need. Now you installed multiple versions of Python. If you want to uninstall a specific version, you can do that with the uninstall command providing the version number you want to uninstall.
$ pyenv uninstall 3.9.1
You already know how to list all the Python the version that can be installed. Another common thing you will do is checking which versions are installed on your system and available to be used in pyenv. This can be done with
$ pyenv versions
This will show a list of all locally installed versions that are available in pyenv. The list list also indicates with a * which version is active at the moment and system is the out-of-the-box version shipped with the operating system. It looks like this:
$ pyenv versions
system
2.7.17
*3.7.3
3.8.0
3.8.5
If you want to switch the current Python version, you have two options. You can set a version globally, which means the version is set for the whole system. Whenever you call python you will be using that version.
$ pyenv global 3.8.0
This sets the global python version to version 3.8.0. The second option is to set a particular version for a single project. To do that, you can just cd into the directory of your project and run
$ pyenv local 3.8.5
This will create a .python-version file in that directory and the Python version 3.8.5 is set for the directory and its subdirectories.
If you want which Python version is active in the current directory, you can check that with the command
$ python --version
Python 3.7.3
It returns the version that is active, here Python 3.7.3.
Now what?
You installed homebrew and pyenv and you learned how to install multiple versions of Python and how to handle them. If you want to find out what else is possible with pyenv, just run
$ pyenv help
to see a list if the supported command and to get the link to the full documentation.
Can you imagine a problem that might come up when working with multiple versions of Python? You might (and will) install additional packages with pip to import new functionalities and libraries. They will depend on particular versions of Python which will for sure lead to conflicts. To show how this can be handled, we will write another blog post on using virtual environments.
