Virtual Environments in Python: What, Why, How?

This is a no-fuss, succinct, condescending, comprehensive explanation of virtual environments (sometimes referred to as a “venv”). My operating system is Linux (Ubuntu), and my IDE is VSCode. I hope yours is too.

After reading this article, you should be able to coherently explain the composition, purpose, and method of implementation of virtual environments to an uninterested spouse or colleague.

WHAT?

A virtual environment or venv in python is, in layman’s speak, a private little space in which particular versions of modules or of Python itself may be installed. Installing or updating modules into the non-venv Python workspace does not affect the version or installation of modules within the venvs.

Similarly, updating modules within a venv has no effect on the version of modules in other venvs, or the non-venv global environment.

WHY?

Consider this nightmare scenario:

1. You write a script using a given version of a given module (say, pandas).
2. The thoughtless a**holes who work tirelessly, free of charge, on maintaining pandas decide to deprecate a few functions in the next version, some of which your script was reliant upon.
3. You update pandas and are none the wiser (assuming you, like me, prefer waterboarding to reading release notes) and go to work on your next cute little script project.
4. Sometime in the future you return to your original little script (from step 1) and notice it no longer functions.

What is one to do? If you downgrade to the earlier pandas version, you risk ruining your new cute little projects. If you stick with the current version, you need to find the enthusiasm to re-write your old waste-of-time script. Is there no way out?

Enter the venv

Employing a virtual environment for each project allow different versions of modules to be maintained between projects. The old version of pandas remains intact for one project, the newer versions are free to be updated in others. Simple as that.

HOW?

Installation and activation

Alright. I will be performing all this through VSCode, as it is the location in which I will be using my virtual environment after creating it.

1. Click File > Open Folder…
2. Select the directory in which you wish your virtual environments to live. It is strongly recommended that you create a specific project directory and select it. The virtual environment will produce a sub-directory of special virtual environment files, which you ought to not disturb.
3. Open a terminal by clicking Terminal > New Terminal

Below are all the commands for the installation in a single block. I will then explain each line individually. Ensure you replace project_env_name with your own project’s name.

$ sudo apt install python3-venv
$ python3 -m venv project_env_name
$ source project_env_name/bin/activate

Line one installs the module venv (virtual environment) for Python3:

$ sudo apt install python3-venv 

Line two commands the computer “in python3 run the module venv and create an environment called project_env_name”:

$ python3 -m venv project_env_name

Line three activates the virtual environment:

$ source project_env_name/bin/activate

You will notice that the prompt in the terminal will change to signify the virtual environment is running, as below:

(project_env_name)$ 

Selecting the venv as VSCode’s Python Interpreter

This is imperative, you absolutely must do this, else VSCode will still attempt to run your scripts using the global environment, causing much frustration:

1. Press Ctrl + Shift + P and click on “Python: Select Interpreter”
2. Select the virtual environment (you can identify it via the file path)

Done.

Deactivating the virtual environment

Note: once you are finished with your virtual environment, deactivate it as follows to return to the good old shell:

(project_env_name)$ deactivate

HOW (day-to-day)?

Now that you obediently activate your virtual environment before sitting down to your little programming session, you may ask “how does one use the virtual environment for my mundane daily tasks?” Well…

Installing packages

No silly business. To install a package, ensure the virtual environment is activated, then simply run:

(project_env_name)$ pip install pandas

Installing packages of a specific version

In case you were wondering…

(project_env_name)$ pip install requests>=2.0.0,<3.0.0

Upgrading packages

Need I explain why?

(project_env_name)$ pip install --upgrade pandas

Which packages are installed?

Glad you asked! Enter and run the following:

(project_env_name)$ pip list

The output is a list of the packages and versions you have installed on this virtual environment.

Exporting a list of packages and versions installed

Say you have a particular virtual environment set up with many packages of specific versions. You want to create another virtual environment similar to this one, but don’t want to install each package separately. Pip can help. Run the following:

(project_env_name)$ pip freeze

The output is a list of installed modules and their versions. Now try this:

(project_env_name)$ pip freeze > requirements.txt

You have now created a text file containing what the command before simply printed to the terminal. It was created in the main folder of your virtual environment. This text file can be imported as instructions for pip in a separate virtual environment. Let’s do that now.

Importing a list of packages with specific versions

Now we wish to use the requirements.txt file to bring a new virtual environment up to the state of the old one.

Run the following command:

(project_env_name)$ pip install -r requirements.txt

A prudent developer would place this requirements.txt file into source control, while keeping the virtual environment folder out. This is because the virtual environment directory contains the files of many python modules, whereas the requirements file is simply a short text file instructing the venv to install or upgrade its modules.

There you have it.