How to create virtual environments in Python 3 with venv module

Last updated on March 22, 2021 by Enrique Bruzual

Open-source has changed the software landscape not only for end-users but also for software developers. One of the main powers of open-source is the speed at which tools are developed and upgraded. Being an open-source programming language, Python has benefited greatly from this agile development environment. In fact, the Python interpreter is updated so frequently nowadays that it is even hard to keep up with its versions. If that is not enough, Python is empowered by a vast third-party library catalog which is upgraded frequently as well. This vibrant ecosystem of the Python language and its third-party libraries, however, comes with its own set of challenges as well, one of them being version control.

If there only was a way to manage all the versions for both the Python interpreter and installed libraries! Well there is. By using a "virtual environment", we can exactly solve this problem. A Python virtual environment allows you to create a logically isolated software environment for a particular Python project, and choose a version of Python interpreter as well as install any necessary libraries for the project. The idea is for every project to have its own virtual environment. This means that Python tools installed for different projects within their own virtual environments will not interfere with one another. Such isolation makes it possible to manage a Python project, as well as debugging it, sharing it, or shipping it without worrying about the compatibility of run-time environments.

In practical terms, let's say we have developed multiple Flask [1] applications with version X, but we would like to upgrade to the new Y version, but our current apps would not be fully compatible with the new version Y of Flask. If we were to upgrade using the current global environment, the apps we developed could cast errors. The solution would be to have multiple versions of Flask. This can easily be handled by using virtual environments.

[1] Flask is a popular Python framework for developing web sites, APIs, and apps.

In this tutorial, let's find out how to create a virtual environment in Python 3 using the built-in venv module.

Python Global Install

Depending on the OS platform, the Python can be installed in a central location available system-wide or in a particular user's home directory.

On Linux platform, the default Python interpreter is installed under /usr/bin (e.g., /usr/bin/python3.9 for Python version 3.9), and available for all users system-wide.

Python will install its dependencies off a particular Python version directory, in this case again for Linux:

/usr/local/lib/python3.9/dist-packages
/usr/lib/python3/dist-packages
/usr/lib/python3.9/dist-packages

However, having a centralized location for Python version and site-packages could bring some challenges managing multiple versions, as any project we create would reference the system-wide locations. Referring back to our Flask scenario, it could cast some errors if we were to upgrade a library and/or the version of Python is not compatible with one of our apps, as there would be only one version of Flask available system-wide. Our projects depending on Flask version X would run into trouble as now we would have Flask version Y after upgrading.

Note that this is an example. While most Flask upgrades are backward compatibles, there are a few exceptions.

Python Virtual Environments

A Python virtual environment will allow users to install a copy of an already available version of Python in a chosen directory. That is, the Python version must be installed in the system before the new virtual environment can be created.

When a new virtual environment is installed, it will have no new dependencies, but it will have a copy of pip so the desired dependencies can be installed.

Third-party virtual environment tools have been around for a while, such as Pipenv and Pyenv. But since Python 3.6, the Python documentation recommends the built-in cross-platform venv module. It allows developers to create multiple lightweight "virtual environments", including their site directories, with a copy of the Python binary and an option to install its packages.

Creating a Virtual Environment in Python 3.6 and Above

We are going to create a virtual environment using Python's built-in venv module. All we need is Python 3.6 and above. Please download the latest version of Python and install it. We can create as many virtual environments as needed.

First, we need to create a project directory anywhere on our computer, preferably where we keep all of our Python projects and future virtual environments. We can call the sample directory my_project.

$ mkdir /path/to/python/projects/my_project

Let's create our first virtual environment with the venv module.

$ python3 -m venv /path/to/python/projects/my_project/venv

The command above will create a new virtual environment inside our project folder named venv. Anything inside the my_project directory is now part of this virtual environment. The new virtual environment will not inherit any libraries, but we can install libraries by using the pip command after we activate our new virtual environment.

Activating a Virtual Environment

Before we can use our new virtual environment, we need to activate it. We do this by issuing a simple command.

We want to navigate to the my_project folder we created with the virtual environment venv in, to make the activation easier.

$ cd path/to/my_project

Once in the correct location, we are ready to activate our virtual environment with the following command:

$ source venv/bin/activate
(venv) $

When the virtual environment is activated, it will display it on the command prompt of (venv).

Here is a more comprehensive list for activating the virtual environment depending on the platform. On Linux, the invocation of the script varies depending on the shell you are using. Replace <venv> with the path of the directory containing the virtual environment.

Shell	Command for activating a virtual environment
bash/zsh	`source <venv>/bin/activate`
fish	`source <venv>/bin/activate.fish`
csh/tcsh	`source <venv>/bin/activate.csh`

Once activated we can check the status of any installed packages by typing pip list in the command prompt.

(venv) $ pip list

Package    Version
---------- -------
pip        xx.x.x
setuptools xx.x.x

As you can see, a new virtual environment is installed without any libraries. It only shows pip and setuptools with the current version number. For more information on how to use pip, please visit the official Python documentation. Once the virtual environment is activated all the pip commands can be used.

Deactivate a Virtual Environment

Once we are done using the virtual environment or if we just want to deactivate it, we can issue a command.

(venv) $ deactivate

This will disable the virtual environment, thus freeing up computer resources.

Removing a Virtual Environment

For any reason, we may want to remove an existing virtual environment. All we have to do for this is to remove the venv directory manually.

$ rm -r path/to/my_project/venv

Notice that we are removing the virtual environment and not our my_project folder where all our project scripts are found.

Be very careful when removing the virtual environment as it is irreversible. We can always use the graphical user interface of our OS to remove the virtual environment folder.

Conclusion

Although programming in Python has a lot of moving parts for a beginner, virtual environments are an essential part of the development process, just as choosing the right script editor. Python has now made it easier to implement virtual environments with the introduction of the venv module. The sooner any developer starts using virtual environments, the better the experience as a developer will be.