Manage multiple Python versions using pyenv

Have you ever wondered how you or your team will manage to contribute to a project that supports multiple versions of Python? You might not be sure about how you will easily test these projects using the version.

If you are not aware, don’t worry about such a development approach as Python supports managing multiple versions of it using the pyenv.

Running multiple versions of Python and leveraging these versions in the project often becomes challenging. That is where developers can use pyenv.

In this tutorial, let’s grab a complete overview of what pyenv is and how to use it in different operating systems and platforms.



What is pyenv?

pyenv (earlier known as Pythonbrew) is a Python version management tool that allows developers to change and manage various versions of Python within the same project. If your system has one or two versions of the Python interpreter installed, you must also install pyenv.

That way, you can easily leverage the power of the new features and contribute to a project that leverages different versions of Python. More often, various problems arise when switching to different Python versions.

For example, jumping from 3.7 to 3.9 introduces a whole lot of significant features that won’t exist in older versions. So, pyenv helps your project overcome issues and bridge the gap.

pyenv enforces a straightforward idea of utilizing shims (lightweight executables) for passing your command to the correct Python version that your project wants or demands as there are multiple Python versions installed on your system.

These shims get inserted by pyenv within a directory in front of your environment’s PATH. So, as you run a Python command, it will intercept & leverage the appropriate shim to pass to pyenv.

It then specifies the Python version required by your project or application & passes the commands; along to the suitable Python installation. That is how pyenv operates.


pyenv install requirements

Like any other software, interpreters of programming languages also go through a series of updates concerning feature augmentation, patches, bug fixes, and the addition of new concepts.

For installing pyenv for version management of Python projects, you need to have Python installed in your system. Also, pyenv requires the shell path to run before using it.
To activate the pyenv for installation, you need to follow these steps.

  • Install Python from the official website, click here
  • Perform shell setup. For using the version of Python through pyenv, it is necessary to comprehend the shell’s PATH variable. PATH determines where the shell searches for files by the command name. Developers must also make sure that the shell will find the version of Python running by the pyenv & not the one that got installed and detected by default (that is usually the system version).
  • Once the shell set up is ready & set the PATH, you need to activate the environment. pyenv global 3.9.2


Install pyenv on Windows

We can install pyenv in our Windows system using two different ways:
Method 1: Using Chocolatey

    1. We can install pyenv using the Chocolatey command-line package manager in Windows. You have to first install Chocolatey using this instruction.
    2. Once, you have successfully installed this package manager, next you can install pyenv using Chocolatey. For this, you have to open Microsoft PowerShell terminal window through Administrator mode (right click > Run as Administrator) and execute the command: choco install pyenv-win
    3. If you are running the latest build of Windows 10 (build 1905) or newer, you might need to disable your default Python launcher.

Install-Pyenv-Python Opening Windows PowerShell

    1. Start > “Manage App Execution Aliases” and disable the “App Installer” aliases for Python.

Manage App Execution Aliases
Execution alias

  1. After pyenv gets successfully installed on your system, you can close the PowerShell terminal. Now open it again (in administrative mode or normal mode).
  2. Try to execute the command: pyenv –version for checking whether pyenv got successfully installed or not.

Method 2: Using Python Installer Package (PIP)
Another way to install pyenv in your Windows system is using the Python Installer Package (PIP) package manager. It is simple and easy to use.

    1. Open your CLI interface (Command Prompt in administrative mode) or terminal
    2. Then, you have to execute the pip command: pip install –user pipenv
    3. For checking whether the installation got successful or not, you can try checking the version by executing the command: pipenv –version
    4. If it is not showing the version, you might have to add a new environment variable manually.
    5. To add it, search for “Advanced Windows system settings” > Environment Variable > New

System properties and Environment Variables


pyenv global

pyenv global determines that the pyenv version management installer can manage all the different versions of Python across various systems required to carry out the project.

Furthermore, the developers can also set a directory (for a specific project) according to Python versions. Moreover, developers can also create or manage virtual python environments (“virualenv’s”).

All this works on *NIX-style machines (Linux and OS X) without depending on Python. This approach of global works at the user level; hence, developers do not need to implement any sudo commands.

~$ pyenv global
~$ pyenv versions
* system (set by /home/karlos/jmoreira/.pyenv/version)

The global can be overridden with other commands but is applicable to assure you use a specific Python version by default. If you wanted to use 3.9 by default, then you could run the command like:

$ pyenv global 3.9

This command will determine the ~/.pyenv/version to 3.9 from its current version. The global is not specific to any application or dependency but is meant for the entire project.

It is also used to check whether the complete project runs on that Python version or not.
Pyenv version Hierarchy


pyenv local

pyenv local determines the Python version specific to the application. It means if you type the command:

$ pyenv local 2.7.

It will create a .python-version file in your current directory. If you have pyenv installed and activated in your system and development environment, the local command will automatically generate a 2.7 version for you.


How to use pyenv?

Python developers and testers are often required to leverage multiple versions of Python to accomplish a single project. Switching back and forth often becomes a pain and annoys the development process.

Fortunately, developers and testers can install the handy tool pyenv to automate and ease the process of back & forth within a Python project. pyenv tool helps in managing different Python versions.

Developers and testers can use this tool by:

  1. Installing several Python versions and using them for a single project.
  2. You have to set or change the global (i.e., default) Python version within your computer.
  3. You also have to set or change the Python version locally for your specific project.
  4. You might also need to create and manage virtual environments in order to leverage pyenv.


Install pyenv on Linux

Here are the following steps one can follow to install pyenv on their Linux-based development environment/system.

    1. First, you need to install all the required packages necessary for installing various Python versions from sources with the help of the command on your individual Linux distribution.
$ sudo apt install curl git-core gcc make zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libssl-dev (for Debian, Mint, and Ubuntu systems)
yum install git gcc zlib-devel bzip2-devel readline-devel sqlite-devel openssl-devel (for Fedora systems)
yum -y install epel-release (for Cent OS and RHEL systems)
    1. Then, go to the Github repository of pyenv & look for the latest pyenv source tree and install it in the $HOME/.pyenv path with the command given below.
$ git clone $HOME/.pyenv
    1. Next, you will have to set the environment variable PYENV_ROOT where you can point to the path wherein you have installed Pyenv and then export it.
    2. Then, add the $PYENV_ROOT/bin to your system’s environment PATH to run the pyenv command-line utility for executing various system commands.
    3. You might also require enabling pyenv shims & autocompletion by connecting the pyenv init to your shell. Note that you have to do these from your $HOME/.bashrc bash startup file.
$ vim $HOME/.bashrc
    1. You can copy and paste the subsequent lines at the end of the mentioned file.
## pyenv configs
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
    1. Once you make the changes, you can either restart the shell or source the file.
$ exec "$SHELL"
$ source $HOME/.bashrc
    1. Now, you can view all available versions of Python on your system using the command:
$ pyenv install -l
    It also gives satisfaction that your system has successfully installed the Pyenv setup.


Install pyenv on Mac

Installing pyenv on Mac OS systems takes a slightly different approach to accomplish. Here is a list of steps that one should follow to install pyenv on Mac systems.

  1. Install Homebrew: On your Mac system, it is recommended to use Homebrew for installing the pyenv library. In case you already have or using Homebrew, you can jump to the second step. Otherwise, on the command, i.e., the Mac OS terminal, type the following command:
    $ /bin/bash -c "$(curl -fsSL  "")
  2. Now, since you have used Homebrew, installing pyenv becomes easy. Now, update the Brew using the command:
    $ brew update
  3. Now to install pyenv, you need to type the following command:
    $ brew install pyenv
  4. After installing pyenv, if you want to update the pyenv library any time you want, you can try doing it using the command:
    $ brew upgrade pyenv
  5. In case, you have the latest version of pyenv already installed on your Mac system, you will encounter a warning message like this: “Warning: pyenv 1.2.16 already installed”
  6. vi. Now for making your pyenv work in your system, you have to update your shell or terminal’s profile configuration. To make your pyenv work the commands are:
    $ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
    $ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
    $ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.zprofile

Let us understand what the above three command does.

  1. The first command will set an environment variable (PYENV_ROOT) that will indicate to the pyenv’s directory.
  2. The second command will put your installed pyenv at the first of your search path so that your Mac operating system will identify pyenv’s Python before any other Python versions.
  3. The final command will initialize pyenv every time you open your terminal.


pyenv not updating Python version [Error]

Developers may encounter an error while setting the Pyenv environment. It might show some message like “pyenv global x.x.x not changing the Python version.”

In a lot of systems and platforms like Linux or Mac OS, this occurs while setting the pyenv.

So, one can solve this error by adding the following code to the~/.zshrc file:

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


Migrate packages with pyenv

A migration package is a process of shifting or migrating Python packages and libraries from one version of Python to another.

In this process or approach, all the necessary settings, programs, and dependencies get transferred based on your selection criteria. pyenv helps achieve this using a built-in binary package.

  • On Linux and Windows systems, you can follow this approach and type the following command on your system’s terminal.
git clone $(pyenv root)/plugins/pyenv-pip-migrate

It will install the latest version of pyenv-pip-migrate into the $(pyenv root)/plugins/pyenv-pip-migrate directory.

  • On your Mac system, you can open Homebrew and type the following command:
$ brew install pyenv-pip-migrate


Using pyenv to list and install all Python versions

Since you have installed pyenv, now it is time you can install Python through Pyenv.

If you follow this installation technique, you can see a list of Python versions within which you can jump back and forth within your project.

pyenv gives us some commands through which we can check the list of Python versions we can install. The command to check the list of Python versions using pyenv is:

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

list of versions in Cython
The list of Python versions you can see is of Cython. Cython is a superset of Python that aims to provide a C-like performance.

It gets its syntax designs from C programming and can work very fast like that of C. The default Python you install is the Cython version. The 3\. in the –list command defines what are the sub-versions you want pyenv to display in this.
Now, if you wish to install the Jython version of the Python interpreter, the command will be:

$ pyenv install --list | grep "jython"

list of versions in Jython
Jython is another Python implementation meant specifically to run on the Java platform. It was earlier called the JPython.

It allows Python the benefits of running class-based programs that run on JVM.

Finally, if you do not provide an additional parameter to determine the implementation type of Python and simply use the Pyenv –list, you will get to see all the versions pyenv can fetch and leverage within it.

$ pyenv install --list


Switch Python version using pyenv

Once you determine which version of Python you want to install or switch to, you can simply use the following command:

$ pyenv install -v 3.7.3

After switching Python versions


Common pyenv commands

pyenv offers many commands to perform various checks on different versions of Python. These commands become helpful and handy when developers or testers go back and forth dealing with Python versions. Here is a list of available pyenv commands.

    1. pyenv help: It will show the list of all available pyenv commands pyenv caters to, along with a short explanation of what that command does. You can run pyenv help for details on a specific command.
    2. pyenv commands: It will render a list of all available pyenv commands and subcommands that developers and testers can leverage while using pyenv.
    3. pyenv shell: It is used for setting a shell-specific Python version by implementing the PYENV_VERSION environment variable within the shell. This way, it will override application-specific versions as well as the global version. We can write the command like this: $ pyenv shell pypy-2.2.1
    4. pyenv install: You have already encountered the install command previously while listing the Python versions within the pyenv. This command helps in installing a specific version of Python. Here are the flag attributes you can use with the install commands
-l/–list -l/–list It determines the list of all available Python versions you can install
-g/–debug It helps to build a debug version of Python
-v/–verbose Verbose mode: helps in printing the compilation status to stdout
  1. pyenv versions: The “versions” command helps in displaying all presently installed Python versions one after another. $ pyenv versions * system (set by /home/gauravkarlos/.pyenv/version) 2.7.15 3.7.5 3.8-dev
  2. pyenv global: It helps in setting the global version of Python used in all shells by composing the version name into the ~/.pyenv/version file. We can override the version by an application-specific .python version file or by specifying the environment variable PYENV_VERSION .
    $ pyenv global 2.7.6
  3. pyenv local: This command helps in setting a local application-centric Python version by providing the version name to a .python version file. We can override the global version with the pyenv shell command or by setting the environment variable PYENV_VERSION.
    $ pyenv local 2.7.6
  4. pyenv which: This command helps to determine the complete path to the system executable. Since pyenv leverages the shims, this command lets programmers see the complete path from where the executable pyenv is running.
    $ pyenv which pip



I hope you can now contribute to your Python projects more easily by leveraging the potential of the pyenv module. With pyenv, you can move to multiple versions of Python.

It also allows you to test the greatest & latest Python versions and their features without messing up or disrupting the development system.

We have further learned how to install this incredible tool in different systems like Windows, Linux, and Mac OS.

Also, we learned how to check the list of different versions of Python and install them through pyenv. The article also showed how we switch between versions so that we can leverage the features catered to by different Python versions for our project.

Leave a Reply

Your email address will not be published. Required fields are marked *