Pre-requisites

There are couple of things you should know before reading this blog:

• Basics of the Python Programming Language
• What is a Virtual Environment in Python?

With these prequisites being fulfilled, let's dive straight into the blog.

Motivation

Having multiple Python projects is a common occurence as a programmer.

Each project would have their respective python version and their compatible dependencies.

Thus, it is necessary to isolate these python versions and their dependencies from the global python installations and its dependencies so that we reduce version conflicts and have better control over our code.

What is pyenv?

Pyenv is a tool designed to manage multiple Python versions –– whether they are local installations ie virtual environments or global installations –– and their dependencies without interfering with each other.

How Pyenv works:

Pyenv operates by using "shims," which are small executable scripts that intercept Python commands. When you execute a python command, Pyenv's shims redirect the command to the currently selected Python version, ensuring that the correct interpreter is used.

How to install pyenv?

If you are using macOS, you can simply install it using:

brew install pyenv

For operating system specific installation, feel free to follow the guide mentioned here.

How to manage pyenv?

Below are the essential commands every developer would need to manage python installations and different virtual environment.

Frequently Used Commands

First, find your username using:

whoami

To check the list of python versions installed using pyenv

pyenv versions

To check the global list of python versions installed

ls /Users/<username>/.pyenv/*

You can see the "shims" or the aliases which are being used by pyenv, but they refer already installed python versions inside the operating system.

Now, we move towards installation of global and local python versions.

To install a python globally using pyenv

pyenv install 3.13.0

Set a global python environment

pyenv global 3.13.0

Please Note: Setting a Global python version works only once you are outside of the local directory that has a pyenv virtual environment (explained further). So, feel free to set a global python anywhere outside of the local projects' directory, and you won't face any errors.

To install a local environment, use

pyenv virtualenv <python_version_no> <env_name>

for example:

pyenv virtualenv 3.11.8 aifc

Now, there are two ways using which you can activate a virtual environment: manually, and automatically (that is, when you change directory or cd into it).

For manual virtual environment activation:

pyenv activate aifc

This commands activates the virtual environment as and when we invoke it.

For Directory Based Activation:

pyenv local aifc

Pros (& when to use it?):

• This command activates the virtual environment.
• Along with that it also sets the current directory it is in, as the local directory of that environment. So, whenever you change directory to that folder, this environment gets activated by default by pyenv.

When to use it?:

• This command is best for recurring projects and projects which require collaboration.

Cons (& how to mitigate it):

• Entering this command also saves "aifc" –– the local environment name instead of the actual python version used by that virtual environment in your ".python-version" file.

This is not ideal, since once we push this code, we or our peers won't be able to identify which python version needs to be installed for this project.

What we ideally want is –– say instead of "aifc" it was "3.10.13" the python version that was saved. Let's learn how to do that:

How to mitigate this?

1) Add the ".python-version" file name to your ".gitignore" file.

2) Once you do that, save the python version number of the local environment by creating the ".python-version.example" file and saving inside it.

This way the exact version number of the project is saved into the ".python-version.example" file, while the file that sets your environment ".python-version" gets ignored by version control (since you put it inside .gitignore file).

This lets you or your peers know about the python version for that particular project, while you get the benefits of locally changing directory without having to activate or deactivate the respective virtual environment!

Till now, we have learnt how to install pyenv, lookup different python versions, install, and activate local and global pyenv python versions.

Now let us learn how to deactivate the virtual environment:

Once we activate the virtual environment, the directory is ready to be used for the project.

To deactivate the virtual environment (for Directory based activation):

pyenv local --unset

To deactivate the virtual environment (for manual activation):

pyenv deactivate

How to check the currently active pyenv virtual environment

pyenv version

To check python version of the currently active pyenv virtual environment

python --version

Finally, we may need to delete the global python version or the virtual environment we created. Here's how to do that:

Deleting the global python version

pyenv uninstall <version>

Deleting the virtual environment

pyenv virtualenv-delete <env-name>

And that is it!

If you came till the end, thank you so much! It means a lot to me!

"Every strike brings me closer to the next home run." -- Babe Ruth

— Inspired. Motivated. Ready to Go🚀 (@Inspire_To_Win) January 6, 2024

Cheers.

Until next time,

Shreyas