Python Virtual Environments

Learning Objectives

By the end of this lesson, you will understand why professional Python projects use isolated environments and how to create and manage them.

What Is a Virtual Environment?

A virtual environment is an isolated Python environment created specifically for a project.

It allows a project to have its own Python packages and package versions without affecting other projects on your computer.

python -m venv .venv

This creates a virtual environment named .venv.

Why Use Virtual Environments?

Imagine you have two projects.

Installing everything globally can create dependency conflicts.

Virtual environments solve this by isolating the dependencies of each project.

Project A
└── .venv
    └── packages for Project A


Project B
└── .venv
    └── packages for Project B

Dependency Isolation

Suppose Project A needs:

requests==2.31.0

while Project B needs:

requests==2.32.3

Each project can maintain its own environment and dependency versions.

Creating a Virtual Environment

First, open your terminal inside your project directory.

python -m venv .venv

The command uses Python's built-in venv module.

You can also choose another name:

python -m venv myenvironment

However, .venv is a common convention for project environments.

Understanding the Environment Structure

After creating an environment, your project may look approximately like this:

my-project/
│
├── .venv/
│
├── app.py
│
├── requirements.txt
│
└── README.md

The exact contents inside .venv vary by operating system and Python version.

Activating on Windows

In Windows Command Prompt:

.venv\Scripts\activate

In PowerShell:

.venv\Scripts\Activate.ps1

Once activated, your terminal usually displays the environment name.

(.venv) C:\Projects\my-project>

Activating on macOS and Linux

On macOS and Linux, use:

source .venv/bin/activate

After activation, the terminal commonly displays:

(.venv)

The activation command differs because operating systems use different executable and shell layouts.

Verifying the Environment

After activation, check which Python interpreter is being used.

python --version

You can also inspect the Python executable path.

On Windows:

where python

On macOS/Linux:

which python

Installing Packages Inside the Environment

Once the environment is active, install packages normally.

python -m pip install requests

The package is installed into the active environment.

python -m pip list

This allows your project to maintain its own dependencies.

Activate environment
        ↓
Install dependencies
        ↓
Develop application
        ↓
Test application
        ↓
Record dependencies

Deactivating the Environment

When you finish working with the environment, use:

deactivate

The (.venv) indicator should disappear from your terminal.

Virtual Environments and requirements.txt

Virtual environments isolate packages, while requirements.txt records which packages the project needs.

python -m pip freeze > requirements.txt

A requirements file might contain:

requests==2.32.3
pandas==2.2.3
numpy==2.1.3

Another developer can then install the dependencies with:

python -m pip install -r requirements.txt

Recreating an Environment

One of the biggest advantages of this workflow is that environments can be recreated.

Suppose your original environment is deleted.

Create a new one:

python -m venv .venv

Activate it and install dependencies:

python -m pip install -r requirements.txt

Using Multiple Environments

A developer can have many projects, each with its own environment.

Projects/
│
├── ecommerce/
│   ├── .venv/
│   └── app.py
│
├── analytics/
│   ├── .venv/
│   └── analysis.py
│
└── website/
    ├── .venv/
    └── app.py

Each project can maintain its own dependency set.

Virtual Environments in VS Code

VS Code can detect Python environments and allow you to choose which interpreter your project should use.

After creating:

python -m venv .venv

Open the project in VS Code and select the Python interpreter associated with .venv.

If VS Code uses a different interpreter from your terminal, you may see confusing import or package errors.

Virtual Environments and Git

Virtual environments usually should not be committed to your Git repository.

Instead, developers normally commit the project's source code and dependency information.

.venv/

Add it to .gitignore:

.venv/

project/
│
├── .venv/              ← local only
├── .gitignore
├── app.py
├── requirements.txt
└── README.md

Common Mistakes

1. Installing Packages Before Activation

You may accidentally install packages into another environment or the global Python installation.

2. Wrong Python Interpreter

Your editor may be using a different interpreter from your terminal.

3. Committing .venv to Git

The environment directory can be large and is normally unnecessary in source control.

4. Copying .venv to Another Computer

Recreating the environment from dependency information is generally more reliable.

5. Forgetting Which Environment Is Active

Always check the terminal prompt and interpreter path when something behaves unexpectedly.

Practice Exercises

python -m venv .venv

Mini Challenge — Build a Reproducible Project

Create a small Python project that can be recreated on another computer.

Suggested Structure

sales-analyzer/
│
├── .venv/
├── .gitignore
├── analysis.py
├── requirements.txt
└── README.md

Suggested Commands

python -m venv .venv

python -m pip install pandas

python -m pip freeze > requirements.txt

Knowledge Check

Lesson Summary

Virtual environments are a fundamental part of professional Python development. They allow each project to maintain isolated dependencies.

You now understand one of the most important professional Python workflows: environment isolation + dependency management.

Next, we will learn how to find and fix problems in Python programs through systematic debugging.