Understanding Python Virtual Environments

Python virtual environments are useful for managing dependencies and isolating projects. They allow you to set up different environments for each of your Python projects, ensuring that dependencies are managed independently and preventing version conflicts. These detailed instructions will cover everything you need to know about Python virtual environments, including why they're important, how to set up and use them.

What is a Python Virtual Environment?

A Python virtual environment is a self-contained directory that contains the Python interpreter and all of the packages required for a specific project. Using virtual environments allows you to keep dependencies required by various projects separately and prevent conflicts between them. This isolation ensures that each project operates with its own set of dependencies, regardless of what is installed globally on your machine. In essence virtual environments are isolated environments that contain both the code and the dependencies for a project.

Why use virtual environments? 

Isolation: Virtual environments provide an isolated development environment for individual projects allowing us to install only the packages needed by required for the specific project.

Version Control: For instance, one may be working on a legacy application that requires v1.0 of a package and at the same time a newer application which requires v2.0 of the very same package which is incompatible with the legacy application.  In this scenario, a globally installed package could only support one of the applications .  Virtual environments allow one to target these versions of the package to specific projects.

Reproducibility: By using a virtual environment, you can create a consistent and reproducible environment for your project, which is crucial for collaboration and deployment.

Creating and activating a new virtual environment:

Change directories until you are at the project root folder

Example:

Command: A new virtual environment can be created using the following command

  python -m venv <virtual name>

Note:  the name of the virtual environment is arbitrary, see the examples below

Example:  Here I am creating a new virtual environment with the name “project1-venv’

Activate virtual environment:

The virtual environment must be activated after it has been created in order to be used for your project.

To deactivate a virtual environment, simply type ‘deactivate’ in the shell

Installing Python Packages within a Virtual Environment

Once the virtual environment is active any packages installed will be sequestered into the active environment and not to the global scope.

Install packages with ‘pip install <package name>’

Example: Install a package NumPy

Inspect what libraries are installed in the virtual environment using ‘pip list’ command

Example:  

Saving the Python Application Requirements for Distribution and Deployment

Once an application has been developed and is ready for deployment and distribution it is imperative that any required external python packages are accounted for and subsequently installed.  For this, python uses a convention which utilizes a file called ‘requirements.txt’.  This text file will contain a record of all packages installed by pip and then can be later used to recreate the application environment when distributed and deployed to another platform, including Microsoft Azure.

Creating the ‘requirements.txt’ File

In order to create the requirements.txt file, first install all required packages and the run the following command with output redirected to the file requirements.txt

Example:  pip freeze > requirements.txt

Note:  after creation of the requirements.txt one may inspect the file and see that it recorded the name and version if each package installed in the virtual environment

 Recreating the Virtual Environment for Distribution and Deployment 

In order to recreate the virtual environment for distribution and deployment the first step is to create and activate a new virtual environment (see the first section of this document).  Next execute the following command to install all packages with correct versions from the requirements.txt.

Example: pip install -r requirements.txt

Note:  When creating an Azure function app, the azure deployment process will process the contents of the requirements.txt automatically.  One just needs to ensure the requirements.txt was accurately created in your project.

Removing Packages from our Virtual Environment 

In order to remove packages from your virtual environment, once again the pip command is used but with the ‘uninstall’ switch

Example: pip uninstall <package_name>

Note:  Recreate your requirements.txt whenever a package is installed or removed

Corrupted Virtual Environment, Package Reinstall 

It is not unheard of that a virtual environment get corrupted if multiple installs and uninstalls have occurred as there can be instances when packages overwrite or corrupt one another.  If this occurs you can attempt to reinstall the packages, but pip will inform you that packages have already been ‘satisfied’.   To force a reinstall of the entire requirements.txt file contents, use the following command:

Example: pip install -r requrements.txt –ignore-installed

To force the reinstall of a single package, use the ‘ignore’ (I) switch with install command

Example: pip install -I <package name>

Removing a Virtual Environment

A python virtual environment is no different than any other directory on the file system.  To remove it, simply deactivate it (if running), and delete it from the file system.

Example:

Note: All of the above examples were all performed using Windows cmd.

Summary:

Using virtual environments is a best practice for Python development. It keeps your projects isolated, reproducible, and manageable. Using the instructions detailed in this blog post, you may create, activate, deactivate, and delete virtual environments, as well as manage packages with pip.