By default, packages gets installed into the global environment, this means that they become available from anywhere in the system. This may be very useful especially in the case with utility libraries i.e those that perform a general task that may be required by most programs. However, with libraries that performs very specific non-utility tasks, it is essential to install them in isolation away from the global workspace,  and this is where virtual environments comes in.

A virtual environment is basically made up of two components, a Python interpreter and the installed libraries also known as dependencies. Each virtual environment is isolated from other virtual environments, this means that  a change in the dependencies of one virtual environment does not in any way affect another virtual environment. Different virtual environments may also use different versions of Python.

It is a good practice to always manage and work with each project on its own virtual environment.

Virtual environments helps to:

  1. Avoid cluttering the global workspace.
  2. Organize each project on its own workspace.
  3. Conveniently keep and retrieve project's dependencies. 
  4. Prevent version conflicts.

When to use virtual environments

Consider a scenario where you are working on several projects at the same time. Let us assume that one project is on web development and another on game development.

The dependencies for the two projects are apparently different. In one hand, you will need to install web-development libraries and frameworks such as flask or django and on the other you will need to install libraries related to game development such as pygame. This is an obvious case when you would need to have two distinct virtual environments for the projects.

In another case you may be working in closely related projects but with different version of Python or even dependencies. 

How to create a virtual environment

Python comes with a command line tool called venv for creating virtual environments. venv is actually a module that exists in python's standard library.

The following syntax can be used to create a virtual environment from the command-line interface/shell:

Syntax: 
python -m venv <environment_name>

Where environment_name is the name of the virtual environment. The convention is usually to name the environment simply as venv ar env.

python -m venv venv

In the above case, the first venv is referencing the builtin module while the second venv is the name of the virtual environment.

Note that the above command will create the virtual environment in the current working directory where the shell is running. It may be essential to create a new directory, then create the virtual environment and the project's files in that directory.

Create a new directory called "app":

mkdir app

change shell's location to the directory:

cd app

create a virtual environment:

python -m venv venv

Activating a virtual environment

After creating a virtual environment, you will need to activate it so that you can install modules and perform other package management operations on the environment instead of the global workspace. This is one of the most important steps as you are required to perform it in order to do anything inside of that particular environment.

To activate the environment, make sure your cmd/shell is in the same directory as the virtual environment, then run the following command.

on Windows:

venv\scripts\activate
     or
venv\scripts\activate.bat

on Linux system:

venv/scripts/activate

You should replace "venv" above with the name of the virtual environment if you used a different name. 

After running the above command, the name of the virtual environment should appear in parentheses as a prefix in the subsequent lines of the shell/cmd, as shown below.

an ectivated virtual environment

Install and manage packages in a virtual environment

When the virtual environment is active, packages can be installed, uninstalled and generally managed using pip, without affecting global packages and those in other virtual environments.

Initially a virtual environment will have pip and setuptools installed by default. We can view the existing modules by running the pip list command on the activated virtual environment.

pip list command on a newly created virtual environment

It is usually important to ensure that you are working with the latest version of pip. We can run the pip install command with the --upgrade flag to upgrade pip to the latest version. The full command to upgrade pip is as shown below;

python -m pip install --upgrade pip

Running the above command in the activated virtual environment will only upgrade pip within the environment.

We can now install a package in the activated virtual environment using the pip install command with the name of the package to be installed. For example, to install numpy in the activated environment, we will need to run the following command.

pip install numpy

After running the above command, the numpy package will be installed in the virtual environment together with its dependencies if any. We can run the pip list command to view the added packages.

pip list after installing a package.

As you can see above, numpy is now included in installed library.

Note that you can execute literally any pip command on the virtual environment. For example, you can run pip uninstall to remove an installed package.

pip freeze is one of the most important commands when working with virtual environments. This is because it provides us with the installed packages and their exact versions making it possible to reproduce the virtual environment.

pip freeze command

Note that only the external packages are listed by pip freeze.

pip freeze also allows us to specify a file name where the packages and their versions will be written to instead of displaying them on the console. The convention is to use requirements.txt as the name of the file. The pip freeze command with requirements.txt is as shown below. 

pip freeze > requirements.txt

After running the above command a file called requirements.txt will be created in the working directory with its content being the packages and theirs versions.

View this article to see more on how to work with requirement files.

Deactivate the virtual environment

To deactivate an active virtual environment, simply type deactivate and press enter. The name of the virtual environment will disappear from the subsequent lines in the shell.

 deactivate a virtual environment