Image by Author

Want to spend your morning trying out the new features in the latest Python version…And your lunch break sifting through a legacy Python codebase—all without breaking your development environment?

Yes, it is possible. And Pyenv is here to help. With Pyenv, you can install Python versions, switch between versions, and remove versions that you no longer need.

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

Installing Pyenv

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

$ curl https://pyenv.run | bash

This installs Pyenv using the pyenv-installer. 

After the installation is complete, you’ll be prompted to finish setting up your shell environment to use Pyenv. To do so, you can add the following command to your ~/.bashrc file:

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 a Windows machine, check out these detailed instructions on how to install Pyenv. On Windows, you need to install Pyenv in the Windows Subsystem for Linux (WSL).

Installing Python Versions with Pyenv

Now that you’ve installed Pyenv, you can install specific Python versions by running the pyenv install command like so:

$ pyenv install version

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 version yet, so the only version of Python is the system version. Which 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:

$ pyenv install 3.8

The first time you try to install a specific version of Python with Pyenv, you may probably run into errors. Because of some missing build dependencies. No worries. It’s easy to fix!

⚙️ Some Troubleshooting Tips

When trying to install Pyenv on my Linux distro using the pyenv install command, I ran into errors because of missing build dependencies.

This StackOverflow thread contains helpful information on installing the required 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:

$ pyenv install 3.8

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

Similarly run pyenv install to install Python 3.12:

$ pyenv install 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

Setting Global Python Version

With Pyenv, you can set a global Python version. As the name suggests, the global version is the version of Python that’s used anytime you use Python at the command line.

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

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

$ pyenv global 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 seen, this code uses the match-case statement which was introduced in Python 3.10. So you need Python 3.10 or a later version for this code to run successfully. If you try running the script, you’ll get the following error:

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

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

$ pyenv global system

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

Output >>>
Not Found! Status code: 404

If your system Python is an older version, say Python 3.6 or earlier, it's helpful to install a more recent version of Python and set it as the global version.

Setting Local Python Version for Your Project

When you want to work on projects that use earlier versions of Python, you’ll want to install that version to avoid any errors (like method calls that are no longer supported).

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 set the local Python version in the project A's directory like so:

$ pyenv local 3.8.18

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

$ python --version
Python 3.8.18

This is especially helpful when working on older Python codebases.

Uninstalling a Python Version

If you no longer need a Python version, you can uninstall it by running the pyenv uninstall command. Say we don’t need Python 3.8.18 anymore, so we can uninstall it by running the following command:

$ pyenv uninstall 3.8.18

You should see a similar output at the terminal:

pyenv: remove /home/balapriya/.pyenv/versions/3.8.18? [y|N] y
pyenv: 3.8.18 uninstalled

Wrapping Up 

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

In case you’re wondering. Yes, you can use Docker which is an excellent option to make local development a breeze—without worrying about dependency conflicts. But you’d probably feel it’s overkill to use Docker or other containerization solutions everytime you need to work on a new project.

So I think it is still helpful to be able to install, manage, and switch between Python versions at the command-line. You can also explore the pyenv-virtualenv plug-in to create and manage virtual environments. Happy coding!
 
 

Bala Priya C is a developer and technical writer from India. She likes working at the intersection of math, programming, data science, and content creation. Her areas of interest and expertise include DevOps, data science, and natural language processing. She enjoys reading, writing, coding, and coffee! Currently, she's working on learning and sharing her knowledge with the developer community by authoring tutorials, how-to guides, opinion pieces, and more. Bala also creates engaging resource overviews and coding tutorials.