How to use Pyenv: install, uninstall, list multiple versions of Python as local, global

In a previous post, we summarized how to install the latest version of Python on MacOS and Windows. In some cases, however, you may need to use multiple versions or different distributions of Python on a single machine.

For example, FastAPI-centric versions and packages for Web API development, and the Anaconda distribution and packages for data science.

Manually managing these different versions of Python can be a pain. You have to remember directories and keep changing PATH settings. It would be nice to have a program that does this for you.

1. Introducing Pyenv

Pyenv is a program that manages multiple versions of Python for us. You can easily select the version of Python you want to use, and even specify different versions of Python for different projects to run automatically. You can even test a single command with multiple versions of Python.

Let's take a look at how to install pyenv on Mac and Windows, and how to use pyenv to install multiple versions of Python.

2. Installing pyenv on Mac

The easiest way to install pyenv on Mac is via homebrew. Start the installation with the following command.

brew install pyenv

pyenv installs autoconf, openssl, pkg-config and readline together. autoconf is for automation via shell scripts, openssl for SSL/TLS encryption, pkg-config for checking compiler information and readline for command line manipulation.

Once the installation is complete, it is verified with the command that verify version.

pyenv --version

Execution result:

2.1. Adding additional shells

Since pyenv works through a shell, you need to register your own shells. You can do this by entering the following commands for each shell.

2.1.1. Bash

If you are using the Bash shell, type the following command to add 3 lines of code to your ~/.bashtc 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

Add three lines of code to the ~/.profile file as well.

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.profile

If a ~/.bash_profile file exists, add it here as well. Then run the terminal again.

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

2.1.2. Zsh

If you are using the Zsh shell, type the following command to add three lines of code to the ~/.zshrc file, and then restart the terminal.

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

2.1.3. Fish

If you are using the Fish shell 3.2.0 or later, run the following command.

set -Ux PYENV_ROOT $HOME/.pyenv
fish_add_path $PYENV_ROOT/bin

If you are using a version prior to 3.2.0, run the following command.

set -Ux PYENV_ROOT $HOME/.pyenv
set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths

Finally, regardless of the version, add the following command to the ~/.config/fish/config.fish file.

echo 'pyenv init - | source' >> ~/.config/fish/config.fish

Now run the terminal again.

3. Installing pyenv-win on Windows

Since Pyenv is a program that works through shell scripts based on the Unix operating system, it has never been available for Windows. However, a Windows version of Pyenv called pyenv-win has recently been developed. This allows Windows users to take advantage of Pyenv.

Installing pyenv-win is a single command. First, open Windows PowerShell (which is installed by default on Windows) as an administrator. You can also run the Terminal application.

Make sure you see Windows PowerShell Administrator in the title bar, and then type the following commands in sequence.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

If you don't enter the first command, you'll get a permission error like this

If you enter both, the installation will complete normally, like this

Now close the terminal program and restart it. Then let's type the pyenv version check command.

pyenv --version

Execution result:

The installation was successful.

Next, we need to register the paths used by Pyenv in environment variables. Type the following four commands one after the other.

[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

Reopen the terminal and the settings will take effect.

4. How to use pyenv on Mac, Windows

Using pyenv is the same regardless of your operating system. I'll walk you through it on the Mac and just show you screenshots of what I did on Windows. On the Mac, I used the fFsh shell.

Nothing is currently running because the default command to run python on the Mac is 'python3'. Now we'll use pyenv to install a new version of Python.

4.1. Installing Python with pyenv

First, let's check all the versions available for installation by typing the following command.

pyenv install -l

Result of execution:

You'll see tons of distributions and versions, from Python2 to Jython, Graal, Anaconda, and more. To install one of them, you'll need to type in the name of that version.

pyenv install [version_name]

Result of execution:

Once the installation is complete, run the following command to see all the Python versions you have installed on your machine using Pyenv.

pyenv versions

Result of execution:

Above you can see the newly installed pypy3 version in the list. Here's how to set it to the installed Python.

4.2. Setting the Python version with Pyenv

Let's set the version to run our newly installed Python. There are three ways to do this. Let's go through them one at a time.

4.2.1. Set only in current shell

This method enables it only in the current open shell, and the setting is reset when you close the terminal. Run the following command

pyenv shell [version_name]

The result of the execution:

The python command has executed this version. If you restart the terminal and type the command, you will see that it was initialized.

4.2.2. Set in current folder only

If you set a specific version of Python in the current folder, the version you set will be run automatically whenever you enter that folder. Enter the desired folder and type the following command.

pyenv local [version_name]

To test, I created a new folder and tried to set the version.

The result of the execution:

You can see that when you visit the `test' folder, the set python runs, and when you leave the parent folder, it is unset again.

4.2.3. Enable machine wide

Finally, you can ask for a specific version to run on any path. Enter the command below to set this up.

pyenv global [version_name]

Result of execution:

Setting 3.11.1 to global resulted in that version of Python running in both the current folder and the new folder when checked.

The last thing to note is the priority of each Python version set. Number 1 is the highest priority, followed by number 2, and then number 3. In other words, the version set for the current shell only will ignore the global folder, and the version set for the folder will ignore global.

4.3. Other useful commands

In addition to installing and setting versions, Pyenv provides a number of other commands, such as delete and path checking. You can see the commands and their descriptions by typing pyenv to familiarize yourself with them.

Result of execution:

5. Screenshot using Pyenv on Windows

Let's do the same thing we did in Section 4 with explanations on Windows. I will only show screenshots, so please refer to Section 4 for explanations.