Virtual environments

What is a “virtual environment”?

Virtual environments allow us to create isolated installations of Python, along with installed modules. We often create virtual environments for specific projects—so that installing or uninstalling modules for one project does not break dependencies in another project.

Virtual environments make it easy to “pin” specific versions of modules needed for a specific project. We can also create files that indicate the currently installed modules, along with their version numbers that we can share with others working on the same project on their local machine.

To create a virtual environment, we use Python’s venv module.

The venv module supports creating lightweight “virtual environments”, each with their own independent set of Python packages installed in their site directories. A virtual environment is created on top of an existing Python installation, known as the virtual environment’s “base” Python, and may optionally be isolated from the packages in the base environment, so only those explicitly installed in the virtual environment are available.

When used from within a virtual environment, common installation tools such as pip will install Python packages into a virtual environment without needing to be told to do so explicitly.

The syntax for creating a virtual environment is straightforward. At a command prompt,

$ python -m venv [name of or path to environment]

where $ represents the command prompt, and we substitute in the name of the environment we wish to create. If we want to create a virtual environment called “my_venv” we’d use this command:

$ python -m venv my_venv

TipIf you get an error complaining that there is no python…

On some systems, python might be named python3. If you find yourself in that situation, just substitute python3 for python wherever it appears in the instructions.

To use a virtual environment, we activate it.

On macOS

$ . ./my_venv/bin/activate
(my_venv) $

On Windows (with PowerShell)

PS C:\your\path\here >  .\my_venv\Scripts\activate
(my_venv) PS C:\your\path\here >

Notice that in each case after activation, the command prompt changed. The prefix, in this case (my_venv) indicates the virtual environment that is currently active.

To deactivate, use the deactivate command.

A virtual environment is stored within its own folder and you activate the environment to use it. However, you should never store your own files within this folder, nor should you ever make changes, additions, or deletions to any files in the virtual environment folder. This is not where you should store your Python source code or other files. The files within the virtual environment should be managed entirely with venv or pip (unless you are using a third-party package manager like UV or Poetry, in which case you should follow the appropriate instructions for your chosen package manager.

For more on virtual environments and venv see the Python documentation for creation of virutal environments

Copyright © 2023–2026 Clayton Cafiero

No generative AI was used in producing this material. This was written the old-fashioned way.