Manage multiple Python versions using pyenv

pyenv is a simple yet robust tool for managing multiple Python versions. As a Python developer, you might have faced the situation of needing different Python versions for different projects.

pyenv provides an elegant solution to this problem.
In essence, pyenv is a Python version manager. It allows you to switch between multiple Python versions seamlessly.

It’s a fantastic tool to manage the environment of your Python projects, install Python, switch between Python versions, and much more.

 

 

How pyenv works?

pyenv operates by modifying the PATH environment variable and using shims to intercept Python commands.

When you run a command like python or pip, the operating system uses the directories listed in your PATH to find the correct executable.
Here’s how it works:

1. You run a Python command like python or pip.
2. The operating system searches directories in your PATH from left to right.
3. It finds the pyenv shim directory first (since pyenv puts it at the front of your PATH).
4. The shim passes the command along to pyenv.
5. pyenv determines which Python version has been specified by your application.
6. It runs your command with the selected version of Python.

This way, you can switch between Python versions on a per-project basis, all thanks to pyenv.

 

Installing pyenv on Windows

Windows users can use the pyenv-win fork, which is a port of pyenv and is easy to install with the following commands:

# Via pip
pip install pyenv-win --target $HOME\.pyenv

# Via Homebrew
brew install pyenv-win

After running the command, you should close your terminal and open a new one to let the changes take effect.
Note: You need to update your PATH variable to include the Python installation directory if not included.

 

Installing pyenv on Linux

You can install pyenv on your Linux machine by using the pyenv-installer script from the pyenv repository. Here are the commands to do so:

curl https://pyenv.run | bash

This command downloads and runs the pyenv installer.
Next, you’ll need to add pyenv to your shell so that you can use it directly from your terminal:

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc

These commands add the necessary lines to your .bashrc file to set up the environment for pyenv.
After running these commands, you should restart your terminal or run the following command to let the changes take effect:

exec "$SHELL"

 

Installing pyenv on MacOS

On MacOS, you can use Homebrew. Here’s how you can install pyenv using Homebrew:

brew update
brew install pyenv

After the installation, add pyenv init to your shell to enable shims and autocompletion:

echo 'if command -v pyenv 1>/dev/null 2>&1; then eval "$(pyenv init -)"; fi' >> ~/.bash_profile

Once done, you should restart your terminal for the changes to take effect.

 

Checking pyenv version

Once you have pyenv installed, you can check its version by running the following command:

pyenv --version

Output:

pyenv 2.3.23

This command displays the version of pyenv installed on your system. In this example, the installed pyenv version is 2.3.23.

 

Configuring pyenv environment variables

pyenv uses several environment variables to control its behavior. One of the most important is PYENV_ROOT, which defines the location where versions and shims are kept. By default, this is ~/.pyenv.
You can set it like this:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

These commands set the PYENV_ROOT variable and add it to your system PATH.
To initialize pyenv automatically, you can add the following to your shell profile:

if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

This command checks if pyenv is installed (with command -v pyenv) and if it is, initializes it (with eval "$(pyenv init -)").

 

Listing all available Python versions

pyenv gives you access to a vast range of Python versions. To list all available versions for installation, use the following command:

pyenv install --list

Output:

2.1.3
2.2.3
2.3.7
...
3.8.10
3.9.5
...

This list is quite long as it includes all Python versions starting from 2.1.3 up to the most recent one.

 

Installing a specific Python version

To install a specific version of Python, you can use the pyenv install command followed by the version number.

For instance, to install Python 3.9.5, you can use the following command:

pyenv install 3.9.5

Output:

python-build: use openssl@1.1 from homebrew
python-build: use readline from homebrew
Downloading Python-3.9.5.tar.xz...
-> https://www.python.org/ftp/python/3.9.5/Python-3.9.5.tar.xz
Installing Python-3.9.5...
python-build: use readline from homebrew
python-build: use zlib from xcode sdk
Installed Python-3.9.5 to /Users/username/.pyenv/versions/3.9.5

This command downloads and installs Python 3.9.5 to the pyenv versions directory.
After the installation, you can use the pyenv versions command to list all Python versions installed on your system:

pyenv versions

Output:

* system (set by /Users/username/.pyenv/version)
  3.9.5

This output shows that Python 3.9.5 is installed but the system is currently using the global Python version.

 

Setting a global Python version (Switch version)

With pyenv, you can set a global Python version that will be used in all shells by default. To set a global version, use the pyenv global command followed by the version number. For instance:

pyenv global 3.9.5

To confirm the global Python version, use the python --version command:

python --version

Output:

Python 3.9.5

This output indicates that the global Python version is now set to 3.9.5.

 

Setting a local (per-project) Python version

pyenv allows you to set a local Python version on a per-project basis.

This version overrides the global Python version within the directory where it’s set. Here’s how you can do it:
First, navigate to your project’s directory:

cd my_project

Then, set the local version for your project:

pyenv local 3.8.10

This command creates a .python-version file in your current directory with the specified version.
To verify the Python version for the current directory, you can use the python --version command again:

python --version

Output:

Python 3.8.10

This shows that Python 3.8.10 is the version for the current directory, regardless of the global Python version.

 

shell-specific Python version

Shell-specific version is only valid for the current shell session and is not saved to a configuration file. This can be particularly useful if you need to quickly test something in a specific Python version without affecting your global or local versions.

To set a shell-specific Python version, use the pyenv shell command. For example:

pyenv shell 3.8.10

You can confirm the Python version for the current shell using the python --version command:

python --version

Output:

Python 3.8.10

If you close the current terminal and open a new one, the Python version will revert back to the global or local setting.

To clear the shell-specific version within the same session, use the pyenv shell --unset command:

pyenv shell --unset

 

Uninstalling a Python version

If you no longer need a specific Python version, you can easily uninstall it using pyenv.

Use the pyenv uninstall command followed by the version number. For example:

pyenv uninstall 3.9.5

You’ll be asked to confirm the operation. After confirming, the specified Python version will be removed from your system.

 

What is a virtual environment?

A virtual environment is a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages.

It’s a way to isolate your Python project and its dependencies from other projects, ensuring that each project has its own set of dependencies that won’t disrupt others.
The use of virtual environments is crucial when you’re dealing with projects that require different versions of packages or Python itself.

By isolating each environment, you can avoid potential conflicts between package versions.

 

Creating a virtual environment with pyenv

With pyenv, you can create a virtual environment easily. First, ensure that you have the required Python version installed:

pyenv install 3.8.10

Next, create a new virtual environment using the pyenv virtualenv command:

pyenv virtualenv 3.8.10 my-env

This command creates a new virtual environment named ‘my-env’ with Python 3.8.10.
To list all available virtual environments, you can use the pyenv virtualenvs command:

pyenv virtualenvs

Output:

3.8.10/envs/my-env (created from /Users/username/.pyenv/versions/3.8.10)
my-env (created from /Users/username/.pyenv/versions/3.8.10)

This output shows that you have one virtual environment named ‘my-env’ created with Python 3.8.10.

 

Activating and deactivating a virtual environment

To activate the virtual environment, you can use the pyenv activate command:

pyenv activate my-env

Once the virtual environment is activated, the Python version and packages installed in this environment will not affect the rest of the system.
You can confirm the activation by checking the Python version:

python --version

Output:

Python 3.8.10

This shows that the Python version for the current environment is 3.8.10.
To deactivate the virtual environment and return to the global Python version, use the pyenv deactivate command:

pyenv deactivate

 

Deleting a virtual environment

If you no longer need a virtual environment, you can delete it using the pyenv uninstall command, similar to uninstalling a Python version:

pyenv uninstall my-env

After confirming the operation, the virtual environment ‘my-env’ will be removed from your system.

 

pyenv plugins

pyenv supports plugins that extend its functionality. Here are a few useful ones:

• pyenv-update: This plugin allows you to update pyenv and all its plugins with a single command.
• pyenv-doctor: This plugin checks the health of your pyenv installation and Python builds.
• pyenv-which-ext: This plugin adds the pyenv which command that searches for programs in the directories of the current environment.

You can install these plugins using the same method as installing pyenv, but with the plugin’s Git URL instead of pyenv’s.

Real-world use cases of pyenv

Now that you’ve learned how to use pyenv, let’s discuss its applications in real-world scenarios:

1. Testing Across Python Versions: If you’re developing a Python package, you’d likely want to ensure it works across multiple Python versions. pyenv makes it easy to switch between different Python versions for testing.
2. Simplified Python Updates: When a new Python version is released, pyenv allows you to install it alongside your existing versions, without affecting your system Python or other projects. You can then test your projects with the new version before fully switching over.

That concludes our tutorial on pyenv. You’re now equipped with a powerful tool for managing multiple Python versions and virtual environments.

 

Resource

https://github.com/pyenv/pyenv