Too many Python versions to manage? Pyenv to the rescue

Do you want to spend your morning testing new features in the latest version of Python… and your lunch hour examining a legacy Python codebase, all without disturbing your development environment?

If possible. AND Pyenv is here to help. With Pyenv, you can install versions of Python, switch between versions, and remove versions you no longer need.

This tutorial is a quick introduction to setting up and using Pyenv. Then let's get started!

The first step is to install Pyenv. I use Linux: Ubuntu 23.01. So if you are on a Linux machine, the easiest way to install Pyenv is by running the following curl domain:

$ curl https://pyenv.run | bash

This installs Pyenv using the pyenv-installer.

Once the installation is complete, you will be prompted to finish configuring your shell environment to use Pyenv. To do so, you can add the following command to your ~/.bashrc archive:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc

echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc

echo 'eval "$(pyenv init -)"' >> ~/.bashrc

And you're all set to start using Pyenv!

Note: If you are on a Mac or Windows machine, check out these detailed instructions at how to install Pyenv. On Windows, you must install Pyenv on the Windows Subsystem for Linux (WSL).

Now that you have installed Pyenv, you can install specific versions of Python by running the pyenv install command like this:

To check the list of installed Python versions, run the following command:

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

I haven't installed any new versions yet, so the only Python version is the system version. What is Python 3.11 in my case:

$ python3 –version

Python 3.11.4

Let's try to install Python 3.8 and 3.12. Try running this command to install Python 3.8:

The first time you try to install a specific version of Python with Pyenv, you will probably encounter errors. Because some build dependencies are missing. No problem. It's easy to fix!

Some troubleshooting tips

When trying to install Pyenv on my Linux distribution using the pyenv install command, I encountered errors due to missing build dependencies.

This StackOverflow thread contains useful information on how to install the necessary build dependencies for Pyenv. Run the following command to install the missing dependencies:

$ apt-get install build-essential zlib1g-dev libffi-dev libssl-dev libbz2-dev libreadline-dev libsqlite3-dev liblzma-dev

You should now be able to install the Python versions without any errors:

Note: When you install Python 3.x, by default, the latest version is installed. But you also have more granular control and can specify 3.x and to install a specific version of a Python version. You can also run pyenv install --list for a list of all Python versions available to install. This, however, is very long list.

execute similarly pyenv install to install Python 3.12:

Now if you run pyenv versions You'll see Python 3.8 and 3.12 in addition to the system version:

$ pyenv versions
* system (set by /home/balapriya/.pyenv/version)
3.8.18
3.12.0

With Pyenv, you can set a global Python version. As the name suggests, the global version is the version of Python that is used whenever you use Python on the command line.

But be careful to set it to a relatively recent version to avoid errors when running projects that use newer versions of Python.

For example, let's see what happens if we set the global version to Python 3.8.18.

Create a project folder. In it, create a main.py file with the following code:

# main.py

def handle_status_code(status_code):
    match status_code:
        case 200:
             print(f"Success! Status code: {status_code}")
        case 404:
            print(f"Not Found! Status code: {status_code}")
        case 500:
            print(f"Server Error! Status code: {status_code}")
        case _:
            print(f"Unhandled status code: {status_code}")

status_code = 404  # oversimplification, yes. handle_status_code(status_code)

As you can see, this code uses the match-case statement that was introduced in Python 3.10. Therefore, you need Python 3.10 or later for this code to run correctly. If you try to run the script, you will get the following error:

File "main.py", line 2
	match status_code:
      	^
SyntaxError: invalid syntax

In my case, the Python system is version 3.11 which is quite recent. Then I can set the global version to the Python system version like this:

When you now run the same script, you should get the following output:

Output >>>
Not Found! Status code: 404

If your Python system is an older version, say Python 3.6 or earlier, it is useful to install a newer version of Python and set it as the global version.

When you want to work on projects that use older versions of Python, you'll want to install that version to avoid errors (such as calls to methods that are no longer supported).

Let's say you want to use Python 3.8 when working on project A and Python 3.10 or later when working on project B.

Image by author

In such cases, you can configure the local version of Python in project A directory like this:

You can run python --version to check the Python version in the project directory:

$ python --version
Python 3.8.18

This is especially useful when working on older Python codebases.

If you no longer need a version of Python, you can uninstall it by running the pyenv uninstall domain. Let's say we no longer need Python 3.8.18, so we can uninstall it by running the following command:

You should see similar output in the terminal:

pyenv: remove /home/balapriya/.pyenv/versions/3.8.18? (y|N) y
pyenv: 3.8.18 uninstalled

I hope you found this introductory tutorial on Pyenv useful. Let's go over some of the most common commands for quick reference:

In case you were wondering. Yes, you can use Docker, which is a great option to facilitate local development, without worrying about dependency conflicts. But you probably find it excessive to use Docker or other containerization solutions every time you need to work on a new project.

That's why I think it's still useful to be able to install, manage, and switch between versions of Python on the command line. You can also explore the pyenv-virtualenv Plugin to create and manage virtual environments. Happy coding!

Bala Priya C. is a developer and technical writer from India. He enjoys working at the intersection of mathematics, programming, data science, and content creation. His areas of interest and expertise include DevOps, data science, and natural language processing. He likes to read, write, code and drink coffee! Currently, he is working to learn and share his knowledge with the developer community by creating tutorials, how-to guides, opinion pieces, and more.