Ever thought about how development teams contribute to projects that support several versions of Python? Testing a project across multiple Python versions seems like a massive chore when you think about it.

But thankfully, in reality, it’s very easy to do. You can manage multiple Python versions with relative ease using pyenv. 

In this guide, we’ll walk you through what pnenv is, how it works, and how you can use it to manage Python versions.

What is pyenv? How Does it Work?

Initially distributed under the name “Pythonbrew,” pyenv is a version management tool that enables Python users to manage Python versions within a project. If your machine has more than one Python version installed, you may already have pyenv installed on the machine.

The tool enables you to leverage new Python features and contribute to projects that work on various Python versions. What’s important to note is that there are several problems that could potentially arise when switching between Python versions. 

For instance, if you switch from Python 3.7 to 3.9, there is a major difference in the features, with 3.7 having a significantly smaller feature set. The nice thing about pyenv is that it helps bridge the gap between these features and overcome issues that arise from a lack of features.

The basic idea behind the working of pyenv is its straightforward use of shims. 

Shims are lightweight executables, and pyenv uses them to pass your commands to the correct Python version your project is designed to run on from all the versions installed on your machine. 

When you install pyenv, the shims are introduced to a directory where the environment’s PATH is. This way, when a Python command is run, pyenv intercepts it and directs it to the appropriate shim. 

At this point in the process, it identifies the Python version that your project requires and then passes the command to the right Python version. 

Installation Requirements for pyenv

Like any other application, a programming language’s interpreter also receives updates. The updates may improve upon a range of features, involve patches, introduce bug fixes, or add new features. 

To use pyenv on your machine for Python version management, the machine will need to have Python installed on it. Additionally, pyenv needs the shell PATH to work correctly. 

Let’s go over the steps you have to take to activate pyenv for installation on your machine:

• Visit the official Python website and install it on your machine.
• Set up the shell as required – to enable pyenv to navigate Python versions and choose the appropriate one, it must work with the shell’s PATH variable. The role of PATH is that it establishes where the shell needs to search for files depending on the command. For this reason, you must ensure that the shell finds the Python version that pyenv is running rather than the version that it has detected by default (typically the system version).
• You must activate the environment when the shell is ready, and the PATH is set appropriately. We’ll explore how in the following two sections.

pyenv global

The main function of pyenv global is ensuring that pyenv can work with all the Python versions across machines using different operating systems that a development team uses to create a project.

You can set a directory for any project you are working on, naming it according to the Python versions it’s working with. pyenv also gives developers the flexibility to create and manage virtual environments. 

These features work on Linux distros and OS X and don’t depend on Python. Taking the global approach, therefore, works at the user level. In other words, there is no need to use any sudo commands to use it. 

An important thing to note is that global can be overridden using other commands. However, you can use a command to ensure that you use a specific Python version by default. For instance, if a developer wants to use 3.9 by default, they could run the following command:

$ pyenv global 3.9

The above line will change the version in ~/.pyenv/version to 3.9. As you might have guessed, the pyenv global is not set specifically for certain dependencies and applications but is meant for entire projects.

You can also run the command above to see if the project runs on the Python version.

pyenv local

This command helps check which Python version works with an application specifically. So, if you run the following command:

$ pyenv local 2.7.

The command will make a .python-version file in the current directory.

If pyenv is installed and activated on the machine and environment, running the command will create a 2.7 version for you.

Using pyenv

Both developers and testers involved with Python projects need to leverage several Python versions to ship a single project. Changing Python versions over and over is time-consuming, challenging, and downright annoying, slowing down progress.

For this reason, pyenv is considered an essential tool by both developers and testers alike. It automates switching between Python versions and makes building and testing a Python project much more convenient. 

As mentioned earlier, the tool makes it easy to manage Python versions. Here are the key steps to using pyenv:

• Install all the Python versions that a project is being built for.
• Set the machine’s default Python version within the computer.
• Set the local Python version specific to the project. 
• Create a virtual environment so you can use pyenv correctly.

A Common Error: “pyenv not updating Python version”

When you set the pyenv environment, there’s a chance that you might come across an error with a message along the lines of “pyenv global x.x.x not updating Python version.” 

Don’t worry, since it’s common for this error to appear on macOS and Linux machines when someone sets the pyenv. 

It’s easy to solve this error by adding the following line of code to the ~/.zshrc file:

eval "$(pyenv init -)"eval "$(pyenv init --path)"

Migrating Packages with pyenv

Migrating a package involves moving a Python library or package between Python versions. 

The process involves transferring all the relevant settings, dependencies, and programs based on the selection criteria. With pyenv, there’s little to worry about since it allows you to pull it off with a built-in binary package.

If you’re on a Windows or Linux machine, all you have to do is enter the following commands on your terminal:

git clone https://github.com/pyenv/pyenv-pip-migrate.git $(pyenv root)/plugins/pyenv-pip-migrate

The command will install the latest pyenv version into the directory mentioned above. You can do the same thing on a macOS machine by launching Homebrew and running the command:

$ brew install pyenv-pip-migrate

Listing and Installing All Python Versions with pyenv

We’ve briefly covered installing pyenv in this post, so let’s go over how you can install Python with the tool. 

Bear in mind that if you install Python as mentioned below, you will see a list of Python versions you can switch between in your project.

There are a few commands supplied by pyenv that show you the Python versions you can install. To get a list of Python versions that are using pyenv on your machine, you can run the command:

$ pyenv install --list | grep " 3\.[678]"

You can expect an output that looks something like this:

Developers might be able to recognize that the list of Python versions above comprises “Cython,” a superset of Python designed to perform like C language. 

The superset gets its syntax from the C language and can run fast like C does. By default, when you install Python, you are installing the Cython version of it. 

In the command, the “3\.” part defines the sub-versions of pyenv that you want to display.

Let’s say you want to install the Jython version of the Python interpreter. You can modify the command we used earlier a little bit and run it. It should look like this:

$ pyenv install --list | grep "jython"

The result of running the command would look something like this:

Jython is an implementation of Python that is designed to run on Java. It was earlier known as JPython and supplies the benefits of running class-based programs on Python that are meant to run on JVM.

You can also not use an additional parameter and run pyenv --list. This will allow you to find the implementation of Python and see all the versions that the pyenv tool is able to fetch. 

Switching Python Versions with pyenv

When you’re ready to change the Python version or install a new one that’s not on your machine, you can run the command:

$ pyenv install -v 3.9.3

The command will download the Python version you've specified, install it along with the collected packages, and let you know whether it was installed successfully and where. 

pyenv Commands You Should Know 

There are many commands that you can use with pyenv, and these commands allow you to perform an array of checks on the many Python versions. The commands supplied by pyenv become invaluable when teams of testers and developers need to go back and forth between Python versions.

Here’s a quick look at the many commands available:

• pyenv commands: This command renders a list of all the commands and subcommands you can use with pyenv. 
• pyenv global: You use this command to set the global Python version that it’ll use in all shells. Using the command will compose the version name into the ~/.pyenv/version file. It is possible to override the global Python versions with an application-specific .python version file. Alternatively, you can also specify the environment variable PYENV_VERSION to do this.
• pyenv help: It outputs a list of all the commands you can use with pyenv, coupled with short explanations of what the commands are meant to accomplish. If you ever need help with the details of what a command does, this is the command you should run. 
• pyenv install: We’ve covered how to use the install command earlier in this post when listing Python versions with pyenv. The command allows you to install a specific Python version, and you can use the following flag attributes with it:
  • -l: It shows you a list of all the installable Python versions.
  • -g: You can build a debug Python version with this flag.
  • -v: It turns on verbose mode, allowing you to print the compilation status to stdout.
• pyenv local: The local command allows you to set a local Python version specific to applications. It does this by supplying the appropriate version name to the .python version file. The command allows you to override the global Python version by setting the PYENV_VERSION or using the pyenv shell command. 
• pyenv shell: It enables you to set a Python version only for the shell using the PYENV_VERSION environment variable within the shell. The command will override not only the global version, but also the application-specific Python version.  
• pyenv versions: You can use this command to display all the Python versions currently installed on the machine. 
• pyenv which: This is the command that allows you to find the complete path to your machine’s executable. As mentioned earlier, pyenv leverages the shims, and the command allows you to see the path where the executable pyenv is running.

Conclusion

With this guide, you should be able to contribute to Python projects without much hassle by using the pyenv tool to the fullest. It allows you to move across several Python versions and test your project on the newest and oldest Python versions – all without disturbing the development system.

You can use pyenv on Linux, Windows, and macOS and check your machine's current Python versions. You can also install new versions of Python with pyenv. We’ve covered how you can switch between Python versions and leverage their different features.