How to Create Virtual Environments in Python

Virtual environments are critical to writing Python software, allowing for isolated, reproducible development setups and avoiding dependency conflicts. They are a standard Python best practice recommended for all projects.

When starting out with Python, a common approach is to install Python on your machine and install various required Python packages via the Terminal. This global approach is common for beginners and developers transitioning from data science. But, as you begin to work on more complex software development projects, managing multiple files, packages, and dependencies is common.

Consider the situation when working on two software projects: Project A and Project B. Both rely on your system-installed version of Python. But Project A relies on installing package X version 1.0, whereas Project B relies on package Y version 2.0. Because of breaking changes in version 2.0 vs version 1.0, if you try to switch between projects, you will get all sorts of errors, and your app will not run.

Imagine you are working on multiple software projects requiring different versions of various packages. How do you keep the projects isolated between one project and another? And how do you share projects with a team where every member has a computer and needs a local configuration? The answer is virtual environments!

What is a Virtual Environment?

A virtual environment is a self-contained directory containing a specific Python version plus any additional Python packages. When you activate a virtual environment, you temporarily change the directory where Python looks for software libraries. As a result, it is possible to work on multiple Python projects on the same machine without any conflicts between their dependencies.

Note that virtual environments assume you are using the same global version of Python. Often, this is not the case and additional tools like pyenv can be used alongside virtual environments when you need to switch between versions of Python itself on your local machine.

Create a Virtual Environment

Python's venv module is officially recommended for creating virtual environments since Python 3.5 comes packaged with your Python installation. While there still are additional older tools available, such as conda and virtualenv, if you are new to virtual environments, it is best to use venv now.

Whenever you are working on a Python project that has external dependencies installed with pip, it is strongly recommended to first create a virtual environment.

Here is how to create a new virtual environment called .venv on Windows and macOS. You might see virtual environments with other names, such as venv or myenv; however, there is growing consensus in the Python community that .venv is the clearest approach.

# Windows
$ python -m venv .venv
$

# macOS/Linux
$ python3 -m venv .venv
$

Activate a Virtual Environment

Our project now has a dedicated virtual environment, but we can only start using it once it is activated. If we run pip install right now to add a package, the package will be installed globally, not in our local virtual environment. To activate the virtual environment, we need to execute a script that comes with the installation.

# Windows
$ .venv\Scripts\Activate.ps1
(.venv) $

# macOS
$ source .venv/bin/activate
(.venv) $

Once we see the name of our virtual environment in the command prompt, (.venv), we know that the virtual environment is active. We're all set to install external packages!

Install Packages

Now that we have created and activated our virtual environment, it is time to install whatever external dependencies our project needs. While it is possible to execute the command pip install <package-name>, it is recommended to use python -m pip instead, which executes pip using the correct version of Python.

(.venv) $ python -m pip install <package-name>

To confirm the package was installed, run the command pip freeze to output all installed packages and their version numbers.

(.venv) $ pip freeze
<package-name>==1.0.0

Deactivate the Virtual Environment

Once you have finished working with a virtual environment, you can deactivate it.

(.venv) $ deactivate
$ 

Your command prompt will return to normal without (.venv), meaning you've exited the virtual environment. If you run commands now with Python or pip it will be with the globally configured Python environment.

To work with a virtual environment again, run the activate script again.

# Windows
$ .venv\Scripts\Activate.ps1
(.venv) $

# macOS
$ source .venv/bin/activate
(.venv) $