Your Guide to pyenv

This is your guide to pyenv for changing and switching between Python versions.

pyenv lets you switch between Python versions. Running multiple Python versions can be a challenge; pyenv makes it easier to change versions of Python. It's simple and discreet, and it follows the UNIX tradition of the single-purpose tool that does one thing well.

It's useful for developers who need access to different versions of the language and those who want to use the latest version of Python without upgrading their entire system. Using pyenv helps you write better Python code.

It is a powerful tool that helps you change the global Python version on a per-project basis. pyenv provides support for specifying different versions in your projects. It does not depend on Python and is made from pure shell scripts, because we do not want to depend on Python to install Python.

In this article, we will discuss pyenv and how it works, including: installing pyenv, listing available versions of Python on your computer, setting a specific version at the global or local level, and uninstalling an old version of Python from your computer. Read on!

How pyenv Works to Change Versions of Python

pyenv works through the .python-version file. When you change to a Python version (by using pyenv global or pyenv local), it creates or updates this file with all of your current settings. It helps you manage multiple versions of Python on your system.

It works as a shim at the level where Python calls are translated into the final executable. pyenv uses shim executable injections into the PATH variable to determine which version to use for any given application. It then passes commands along accordingly without user intervention or knowledge about how it works.

pyenv inserts a directory of shims at the front of your PATH variable as follows:

$(pyenv root)/shims:/usr/local/bin:/usr/bin:/bin

According to the documentation, shims are lightweight executables that pass your command along to pyenv. For example, if you run pip, your operating system searches PATH for the first executable file named pip. As we've put $(pyenv root)/shims at the beginning of PATH above, the pip of the pyenv is used. (Note that directories in PATH are separated by the colon.)

How to Install pyenv to Change Versions of Python

There are three ways to install pyenv. You can either clone the GitHub repository, use a package manager, or use pyenv-installer.

Before going further, it is essential to note pyenv was initially not supported in the Windows operating system. It is now possible to install it with pyenv-win. If you are a Windows user, you can install pyenv in a Linux subsystem using one of the methods described below.

Installing pyenv by Cloning the GitHub Repository

Let’s go through the steps to install pyenv from the GitHub repository. If you are not familiar with GitHub, read about it here.

sudo apt-get update; sudo apt-get install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Next, enter the following command to download pyenv:

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

Next, we need to configure our environment:

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init --path)"\nfi' >> ~/.bashrc

Finally, we restart the shell:

exec $SHELL

Congrats! You have successfully installed pyenv directly from GitHub.

Install pyenv With pyenv-installer

The simplest method to install pyenv on Linux and macOS is by using pyenv-installeR. Once the prerequisites have been installed correctly, you can install pyenv directly with the following command:

curl https://pyenv.run | bash

Then, restart your shell:

exec $SHELL

You can now begin using pyenv. Access its commands by typing pyenv into your terminal.

Install pyenv With Homebrew Package Manager

On Linux or macOS, you can install pyenv with the Homebrew package manager. First, install Homebrew with the following command:

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

Next, we run the following two commands to add Homebrew to our $PATH:

$ echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> /home/xavier/.profile
$ eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Next, we enter the following command:

$ brew update
$ brew install pyenv

As in the previous method, the next step is to configure your environment:

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init --path)"\nfi' >> ~/.bashrc

And restart the shell:

$ exec $SHELL

Well done! You have successfully installed it with Homebrew. If needed, you can access the pyenv documents here.

Now, let’s explore how to use pyenv.

How to Build any Python Version With pyenv

The following command outputs the Python versions installed on your system. Usually, you only have one version of Python installed: the system version.

$ pyenv global system
$ pyenv versions
* system (set by /home/xavier/.pyenv/version)

Let's install different versions of Python. You can choose any from the list of available Python versions. We list them by doing the following:

$ pyenv install --list

From the list, we choose to install Python 3.9.9 and Python 3.10.0:

$ pyenv install 3.9.9
$ pyenv install 3.10.0

Now, let’s check which versions of Python are installed in our system:

$ pyenv versions
* system (set by /home/xavier/.pyenv/version)
3.10.0
3.9.9

The asterisk shows the system version of Python is active. But we see versions 3.9.9 and 3.10.0 are also installed.

Now that we have multiple versions of Python installed, we can choose which version to use and in which instances.

How to Set the Python Version With pyenv

pyenv makes it easy to switch between different versions of Python. For example, to set Python 3.10.0 as the global version, use pyenv global as follows:

$ pyenv global 3.10.0
system
* 3.10.0 (set by /home/xavier/.pyenv/version)
3.9.9

You can set the Python version of your choice by replacing the version number with the number of your choice.

We can use pyenv to define a project-specific, or local, version of Python. For example, let’s create a LearnPython directory set with Python 3.9.9.

~$ mkdir LearnPython
~$ cd LearnPython
~/LearnPython$ pyenv local 3.9.9
~/LearnPython$ Python -V
Python 3.9.9

It indicates the Python version is set to 3.9.9 at the local level. pyenv local command creates a .python-version file with the version number in the current directory.

When pyenv tries to determine which Python version to use, it searches for this file in the current and all parent folders. When it finds one, it uses the version specified in it. If it reaches your home folder without finding any .python-version file, it uses the global version.

~/LearnPython$ cd ..
~$ Python -V
Python 3.10.0

When you go back to the global level, Python 3.10.0 is still in use.

If you navigate back to the LearnPython folder and run Python -V, the output shows it is not the global version of Python but instead is the version set last with the pyenv local command.

You can set the version of Python to be used in the current shell with pyenv shell as follows:

pyenv shell 3.9.9

This command activates the version specified by setting the PYENV_VERSION environment variable and overwrites any local or global settings you may have just for this terminal session. Similarly, you can set any Python version of your choice in your virtual environment.

How to Locate a Python Version

The pyenv which command helps identify where the current Python executable is located. It shows the full path to the executable.

$ pyenv which python
/home/xavier/.pyenv/3.10.0/bin/python

Next, let’s explore how to uninstall a Python version with pyenv.

How to Uninstall a Python Version With pyenv

Let’s see how to uninstall a Python version with pyenv.

But first, a word of caution. Because macOS needs Python, DO NOT remove any versions of Python from the following folders:

• /usr/bin
• system/Library

These versions of Python are installed by Apple and used by macOS and other software. Deleting Python from these directories breaks macOS and forces you to reinstall the operating system on your computer.

In addition, some projects may need specific versions of Python, so you need to remain cautious when deleting a Python version. For example, NumPy needs Python 3; without it, NumPy does not work. This is one example highlighting the importance of using a Python requirements file.

To uninstall Python from pyenv, we list all the Python versions. We then remove the Python version we no longer want with the uninstall command.

Let’s list the Python versions:

$ pyenv versions
* system (set by PYENV_VERSION environment variable)
3.10.0
3.9.9

Let’s uninstall the Python versions we no longer want:

$ pyenv uninstall 3.10.0
$ pyenv uninstall 3.9.9

And the final result:

$ pyenv versions
* system (set by PYENV_VERSION environment variable)

Now you know how to install and use pyenv to change versions of Python or switch between Python versions. I hope you have enjoyed this guide.

Your next step is to improve your Python skills. Check out our Python programming track here. It is a course designed for data analysts who want to upskill in Python and increase their market value.

Also check out these other helpful resources, such as some ideas to practice your Python skills, our curated list of the best Python talks, and our list of the best Python code editors.

Happy coding!