5  Virtual Environment in Python

When starting a new Python project, it’s essential to create a virtual environment to manage dependencies and isolate the project’s Python interpreter. This guide will walk you through setting up a virtual environment using Python’s built-in venv module and managing dependencies with pip and requirements.txt. We’ll also cover how to configure the virtual environment in Visual Studio Code (VS Code) for a seamless development experience.

5.1 Why Use venv?

venv creates an isolated, sandbox-like Python environment for each of your projects. This is crucial because it allows you to manage dependencies, libraries, and even Python versions on a per-project basis without affecting other Python projects or the global Python environment. This isolation prevents conflicts between project dependencies and ensures consistency across development, testing, and production environments.

For example, if you’re working on two projects that require different versions of the same library, you can create separate virtual environments for each project. This way, you can install the required library versions in their respective environments without worrying about conflicts. In Figure 5.1, we illustrate an example project structure with separate virtual environments for two projects. ProjectA and ProjectB each have their own virtual environment (.venvA and .venvB, respectively) containing the required packages for the project.

Projects/
β”œβ”€β”€ ProjectA/
β”‚   β”œβ”€β”€ .venvA/
β”‚   β”‚   β”œβ”€β”€ Scripts/
|   |   |   β”œβ”€β”€ activate
|   |   |   └── python.exe (this version can be python3.9.exe, for example)
β”‚   β”‚   β”œβ”€β”€ Lib/
β”‚   β”‚   β”‚   └── site-packages/
β”‚   β”‚   β”‚       β”œβ”€β”€ packageX-v1.0
β”‚   β”‚   β”‚       β”œβ”€β”€ packageY-v2.0
β”‚   β”‚   β”‚       └── packageZ-v3.0
β”‚   └── main.py
β”‚
└── ProjectB/
    β”œβ”€β”€ .venvB/
    β”‚   β”œβ”€β”€ Scripts/
    |   |   β”œβ”€β”€ activate
    |   |   └── python.exe (this version can be python3.13.exe, for example)
    β”‚   β”œβ”€β”€ Lib/
    β”‚   β”‚   └── site-packages/
    β”‚   β”‚       β”œβ”€β”€ packageX-v2.0
    β”‚   β”‚       β”œβ”€β”€ packageY-v1.0
    β”‚   β”‚       └── packageZ-v4.0
    └── main.py
Figure 5.1: Example project structure with separate virtual environments for ProjectA and ProjectB. Each environment contains the required packages for the respective project. Notice that the packages can have different versions in each environment and that the Python interpreter is isolated within the environment.
Development, Testing, and Production Environments

You can create separate virtual environments for development, testing, and production to ensure consistency across different stages of your project. This practice helps prevent issues caused by differences in dependencies and configurations between environments.

  • Development Environment: Used for writing and testing code. It may contain additional tools and libraries for debugging and development.
  • Testing Environment: Used for running automated tests to ensure the code works as expected. It should mirror the production environment as closely as possible.
  • Production Environment: The final environment where the code runs in a live or production setting. It should be stable and contain only the necessary dependencies.

5.2 Installing venv

  • On Linux: If you’re using a Debian-based system (like Ubuntu), you can install venv via apt:

    sudo apt-get install python3-venv

  • On Windows: You don’t need to install venv separately as it comes pre-installed with Python 3.3 and later versions. Just ensure you have the correct Python version installed.

5.3 Creating a Virtual Environment

Once venv is installed, you can create a new virtual environment for your project. The version of Python you use to create the environment will be the default Python interpreter for that environment. For example, to create a virtual environment in a project directory on Windows, run the following command:

PS C:\path\to\your\project> python -m venv .venv

If you have multiple Python versions installed, you can specify the version to use when creating the virtual environment. For example, to use Python 3.13, you would run:

PS C:\path\to\your\project> python3.13 -m venv .venv

The environment will be created in the .venv directory within your project. This directory will contain the Python interpreter, standard library, and pip package manager for the virtual environment. If you want to use the system’s site packages in your virtual environment (i.e., the packages already installed in the global Python environment), you can add the --system-site-packages flag when creating the virtual environment:

PS C:\path\to\your\project> python -m venv .venv --system-site-packages

Notice that .venv is a common convention for naming virtual environments, but you can choose any name you prefer (e.g., venv, env, etc.).

Where Is Python Installed?

In Windows, you can find the path to the Python interpreter by running the command Get-Command python in PowerShell. This command will show the path to the Python interpreter.

For example, if you have Python 3.13 installed and configured in your PATH as the default Python version, you would see something like this:

PS C:\path\to\your\project> Get-Command python

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Application     python.exe                                         3.13.150.… C:\Users\UserName\AppData\Local\Programs\Python\Python313\python.exe

If you have multiple Python versions installed, you can check the path to a specific version by running Get-Command python3 (or python2, etc.):

PS C:\path\to\your\project> Get-Command python3

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Application     python3.exe                                        0.0.0.0    C:\Users\UserName\AppData\Local\Microsoft\WindowsApps\python3.exe

5.4 Activating the Virtual Environment

To activate the virtual environment:

  • On Unix systems:

    source .venv/bin/activate

  • On Windows:

    .venv\Scripts\activate

Activation changes your shell’s prompt and configures your environment to use the Python interpreter and libraries from the .venv directory. You will see the name of the virtual environment in your shell prompt to indicate that it’s active, for example:

(.venv) C:\path\to\your\project>

5.5 Setting Up in Visual Studio Code (VS Code)

To ensure consistency, set the Python interpreter in VS Code to the one in your virtual environment:

  1. Open the Command Palette (Ctrl + Shift + P).
  2. Type and select Python: Select Interpreter.
  3. If the interpreter is not listed, click on Enter interpreter path... and navigate to your virtual environment’s interpreter (e.g., .venv\Scripts\python.exe on Windows).

This guarantees that VS Code uses the correct Python interpreter for debugging and running your code.

You might also need to select the kernel for the interactive window when executing Jupyter notebooks:

  1. Open a Jupyter notebook.
  2. Click on the kernel name in the top-right corner.
  3. Select the kernel corresponding to your virtual environment.

Example of choosing a virtual environment as the kernel in VS Code.

5.6 Managing Dependencies

Once your project is set up, you can install dependencies using pip as usual. The packages will be installed in the virtual environment, keeping them separate from other projects.

When you need to share your project with others, you can export the dependencies to a requirements.txt file and install them in another environment. This way, you can ensure that your project’s dependencies are consistent across different environments.

5.6.1 Creating a Requirements File

A requirements.txt file lists all the Python packages your project depends on. You can create one by running:

(.venv) PS C:\path\to\your\project> pip freeze > requirements.txt

This command lists all installed packages in the current environment and saves them to requirements.txt.

5.6.2 Installing from Requirements

To install all dependencies listed in requirements.txt, use:

(.venv) PS C:\path\to\your\project> pip install -r requirements.txt

This installs all the packages and their specific versions as listed in your requirements.txt, ensuring consistency across environments.

Note: To avoid installation errors, make sure the virtual environment is activated and not being used elsewhere (e.g., in a Jupyter Notebook).

5.7 Projects with Multiple Environments

For projects that require multiple virtual environments (e.g., one for development and another for testing), you can create separate environments and manage them accordingly. Each environment can have its own set of dependencies, allowing you to isolate and control the packages used in different stages of your project.

5.8 Avoid Cloud Storage for Virtual Environments

Avoid storing your virtual environment in cloud storage services like Dropbox or Google Drive. These services can cause issues with file locking and synchronization, leading to corruption or conflicts in the virtual environment.

For example, if you activate the virtual environment on one machine and then switch to another machine without syncing the environment, you may encounter issues due to the differences in the environment paths and configurations.

5.9 Exclude Virtual Environment from Version Control

When working with virtual environments, it’s essential to exclude the environment directory (e.g., .venv) from version control systems like Git. Instead, include a requirements.txt file to manage dependencies. This practice ensures that collaborators can recreate the environment easily without sharing unnecessary files.

For example, you can add the virtual environment directory to the .gitignore file to prevent it from being tracked by Git:

# .gitignore
.venv/