pyenv – Simple tool to manage multiple python versions

With Python 3.11 out, developers must be looking to try this newer version but might be reluctant as they don’t want to mess up their development environment. The best way to install multiple versions of python is by using pyenv. It is a simple python version management tool, which helps you in avoiding conflicts between different python versions. It also comes equipped with a few plugins that provide virtual environment functionality, manage pyenv updates, verify build dependencies, & lookup for any system commands.

First, some bad news for Windows users. pyenv doesn’t officially support Windows. If you want to use it on Windows, you can do it through Windows Subsystem for Linux or can try this pyenv-win fork.

How to install pyenv?

It builds python from the source, which means we will need to install any required OS-level dependencies. For macOS, these are the dependencies

$ brew install openssl readline sqlite3 xz zlib

#Tip: When running Mojave or higher (10.14+) you will also need to install the additional SDK headers:

$ sudo installer -pkg /Library/Developer/CommandLineTools/Packages
	/macOS_SDK_headers_for_macOS_10.14.pkg -target /

Once we have any required dependencies, we can install it using these command

$ curl | bash
$ brew install pyenv

You should also add these to the ~/.bashrc file. This will load pyenv automatically. It makes working with pyenv and virtual environments much easier.

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

How to use pyenv?

  • How to Install any python version?
$ pyenv install <python-version>
  • How to look at all the installed versions available?
$ pyenv versions
  • How to remove any installed python versions?
$ rm -rf ~/.pyenv/versions/<installed-python-version>
$ pyenv uninstall <installed-python-version>
  • How to check actual path of active python or any command?
$ pyenv which python
$ pyenv which <any-command>
  • How to create a virtual environment?
$ pyenv virtualenv <python-version> <environment>
  • How to activate and deactivate any virtual environment?
$ pyenv activate <environment-name>
$ pyenv deactivate <environment-name>
  • Specifying folder level python or virtual environment to be used
$ pyenv local <python-verison>
$ pyenv local <environment-name>
  • Specifying global level of python or virtual environment
$ pyenv global <python-version>
$ pyenv global <environment-name>
  • Activating any python version and virtual environment for the current shell
$ pyenv shell <python-version>
$ pyenv shell <environment-name>

How does PYENV selects which python version to use

You might have noticed that there are multiple ways of selecting or activating python versions or virtual environments. These ways are –

  1. Using SHELL command
  2. Using local command
  3. Using global command
  4. Also, we have pre-existing system python

Pyenv determines which python version to use by reading it from the following sources in the order given:-

  1. It gives priority to any python version set up by pyenv shell command. When we use this command, it creates an environment variable called PYENV_VERSION in the current shell session.
  2. Next, it gives importance to any folder or application-specific python version set up by using pyenv local command. When we use this command, it creates a .python-version file in the current directory. We can always read this file to know the activated python version.
  3. If it doesn’t find a .python-version in the current directory, it looks for it recursively. It means that pyenv will look for this file in the parent directory and then so on. It will use the first .python-version file found.
  4. If it doesn’t find any.python-version file, it will use the python version set up by pyenv global command. When we use this command, it creates a file i.e. $(pyenv root)/version.
  5. If the global version file is not present, pyenv will use the system python.

It can be a little confusing in the beginning, so you can use the following way of working with different python versions

  1. pyenv shell <version> — Select the current shell sessions
  2. pyenv local <version> — Set it up for the current directory so that it selects it automatically
  3. pyenv global <version> — Set it up globally for the user account

Uninstalling Pyenv

To completely uninstall pyenv, we can start by removing its root directory. We can delete all python versions that were installed under $(pyenv root)/ versions/directory

$ rm -rf $(pyenv root)

$ brew uninstall pyenv


You can read the below links for more info about it


%d bloggers like this: