Module 20 - Virtual Environments

Virtual environments allow you to create isolated Python environments for different projects, preventing dependency conflicts and ensuring reproducibility.

1. Why Virtual Environments?

The Problem

# Project A needs Django 3.2
pip install django==3.2

# Project B needs Django 4.0
pip install django==4.0  # ❌ Overwrites Django 3.2!

The Solution

Each project gets its own isolated environment with independent dependencies.

Project A/
  └── venv/  → Django 3.2

Project B/
  └── venv/  → Django 4.0

Benefits

✅ Avoid dependency conflicts
✅ Easier project sharing and deployment
✅ Clean system Python installation
✅ Test different package versions safely

2. Creating Virtual Environments with `venv`

2.1 Basic Creation

# Create virtual environment
python -m venv myenv

# Directory structure created:
# myenv/
#   ├── Scripts/      (Windows)  or  bin/  (Unix)
#   ├── Lib/
#   ├── Include/
#   └── pyvenv.cfg

2.2 Activating the Environment

Windows (PowerShell):

.\myenv\Scripts\Activate.ps1

Windows (Command Prompt):

myenv\Scripts\activate.bat

macOS/Linux:

source myenv/bin/activate

After activation, your prompt changes:

(myenv) C:\Users\YourName\project>

2.3 Deactivating

deactivate

3. Managing Packages with `pip`

3.1 Installing Packages

# Activate environment first
# (myenv) $

# Install a package
pip install requests

# Install specific version
pip install flask==2.0.1

# Install multiple packages
pip install django pandas numpy

# Install from requirements file
pip install -r requirements.txt

3.2 Listing Installed Packages

# List all installed packages
pip list

# Output:
# Package    Version
# ---------- -------
# requests   2.28.1
# Flask      2.0.1
# ...

# Show outdated packages
pip list --outdated

3.3 Viewing Package Details

# Show package information
pip show requests

# Output:
# Name: requests
# Version: 2.28.1
# Summary: Python HTTP for Humans.
# Location: C:\...\site-packages
# Requires: charset-normalizer, idna, urllib3, certifi

3.4 Upgrading and Uninstalling

# Upgrade a package
pip install --upgrade requests

# Upgrade pip itself
python -m pip install --upgrade pip

# Uninstall a package
pip uninstall flask

# Uninstall all packages (careful!)
pip freeze | xargs pip uninstall -y  # Unix

4. Requirements Files

4.1 Creating `requirements.txt`

# Generate requirements from current environment
pip freeze > requirements.txt

Example requirements.txt:

Flask==2.0.1
requests==2.28.1
pandas==1.5.3
numpy==1.24.2
python-dotenv==0.20.0

4.2 Installing from `requirements.txt`

# Install all dependencies
pip install -r requirements.txt

# Upgrade all packages in requirements.txt
pip install --upgrade -r requirements.txt

4.3 Advanced Requirements

Specifying version ranges:

# Exact version
Flask==2.0.1

# Greater than or equal
requests>=2.28.0

# Compatible release (same major.minor)
Django~=4.0.0

# Version range
numpy>=1.20.0,<2.0.0

# Latest version
pandas

Multiple requirements files:

# requirements.txt (production)
Flask==2.0.1
psycopg2==2.9.3

# requirements-dev.txt (development)
-r requirements.txt
pytest==7.2.0
black==22.10.0
flake8==5.0.4

Install dev requirements:

pip install -r requirements-dev.txt

5. Best Practices

5.1 Project Structure

my-project/
│
├── venv/                 # Virtual environment (not in git)
├── src/                  # Source code
│   ├── __init__.py
│   └── main.py
├── tests/                # Test files
│   └── test_main.py
├── requirements.txt      # Dependencies
├── README.md
├── .gitignore           # Ignore venv, __pycache__, etc.
└── setup.py             # Package configuration (optional)

5.2 `.gitignore` for Python Projects

# Virtual environments
venv/
env/
ENV/

# Python cache
__pycache__/
*.py[cod]
*$py.class

# Distribution / packaging
dist/
build/
*.egg-info/

# IDEs
.vscode/
.idea/
*.swp
*.swo

# Environment variables
.env

# OS
.DS_Store
Thumbs.db

5.3 Naming Conventions

# Common virtual environment names
venv
env
.venv
.env

# Project-specific
myproject-env
myproject-venv

Note

Always add virtual environment directories to .gitignore - never commit them to version control!

6. Working with Multiple Python Versions

Using Specific Python Version

# Create venv with specific Python version
python3.9 -m venv myenv39
python3.11 -m venv myenv311

# Or on Windows
py -3.9 -m venv myenv39
py -3.11 -m venv myenv311

7. Alternative Tools

7.1 `virtualenv` (More Features)

# Install virtualenv
pip install virtualenv

# Create environment
virtualenv myenv

# Create with specific Python
virtualenv -p python3.9 myenv

7.2 `pipenv` (pip + venv Combined)

# Install pipenv
pip install pipenv

# Create environment and install packages
pipenv install requests flask

# Activate environment
pipenv shell

# Install dev dependencies
pipenv install pytest --dev

# Generate Pipfile.lock (like package-lock.json)
pipenv lock

Pipfile example:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
flask = "*"
requests = ">=2.28.0"

[dev-packages]
pytest = "*"
black = "*"

[requires]
python_version = "3.11"

7.3 `conda` (Anaconda/Miniconda)

# Create conda environment
conda create -n myenv python=3.11

# Activate
conda activate myenv

# Install packages
conda install numpy pandas matplotlib

# Deactivate
conda deactivate

# List environments
conda env list

# Export environment
conda env export > environment.yml

# Create from yml
conda env create -f environment.yml

8. Practical Workflow

Starting a New Project

# 1. Create project directory
mkdir my-project
cd my-project

# 2. Create virtual environment
python -m venv venv

# 3. Activate environment
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Unix/macOS:
source venv/bin/activate

# 4. Upgrade pip
pip install --upgrade pip

# 5. Install packages
pip install flask requests python-dotenv

# 6. Freeze dependencies
pip freeze > requirements.txt

# 7. Create .gitignore
echo "venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore

# 8. Initialize git
git init
git add .
git commit -m "Initial commit"

Cloning an Existing Project

# 1. Clone repository
git clone https://github.com/user/project.git
cd project

# 2. Create virtual environment
python -m venv venv

# 3. Activate environment
source venv/bin/activate  # or .\venv\Scripts\Activate.ps1

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run project
python main.py

9. Troubleshooting

Activation Script Execution Policy (Windows)

If you get an error about execution policies:

# Check current policy
Get-ExecutionPolicy

# Set policy for current user (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run with bypass
PowerShell -ExecutionPolicy Bypass -File .\venv\Scripts\Activate.ps1

Can't Find Python

# Verify Python installation
python --version
python3 --version

# Windows: Use py launcher
py --version
py -3.11 --version

# Check Python location
which python    # Unix/macOS
where python    # Windows

Package Installation Fails

# Update pip
python -m pip install --upgrade pip

# Install with verbose output
pip install package-name -v

# Clear pip cache
pip cache purge

# Install from source
pip install --no-binary :all: package-name

10. Docker Alternative

For maximum isolation, consider Docker:

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

Benefits:

Complete environment isolation (OS, Python, packages)
Consistent across all machines
Easy deployment

11. Comparison Table

Tool	Purpose	Pros	Cons
`venv`	Basic virtual env	Built-in, lightweight	Basic features only
`virtualenv`	Enhanced virtual env	More features	External package
`pipenv`	pip + venv combined	Modern workflow	Slower, extra layer
`conda`	Scientific computing	Handles non-Python deps	Heavy, slower
`poetry`	Modern dependency mgmt	Excellent for packages	Learning curve
`Docker`	Full isolation	OS-level isolation	Resource overhead

Summary

✅ Virtual environments isolate project dependencies
✅ Use python -m venv to create environments
✅ Always activate before installing packages
✅ requirements.txt tracks project dependencies
✅ Add venv/ to .gitignore
✅ One virtual environment per project

Next Steps

In Module 21, you'll learn:

Type hints and annotations
The typing module
Static type checking with mypy
Writing type-safe Python code

Practice Exercises

Create a virtual environment and install Flask, requests, and pytest
Generate a requirements.txt and recreate the environment from it
Set up a project with separate development and production dependencies
Create a script to automate virtual environment setup for new projects
Practice switching between multiple virtual environments

Challenge

Create a project management CLI tool that:

Initializes new projects with virtual environments
Automatically creates .gitignore and requirements.txt
Provides commands to add/remove dependencies
Tracks which environment is currently active
Warns about outdated packages

1. Why Virtual Environments?​

The Problem​

The Solution​

2. Creating Virtual Environments with venv​

2.1 Basic Creation​

2.2 Activating the Environment​

2.3 Deactivating​

3. Managing Packages with pip​

3.1 Installing Packages​

3.2 Listing Installed Packages​

3.3 Viewing Package Details​

3.4 Upgrading and Uninstalling​

4. Requirements Files​

4.1 Creating requirements.txt​

4.2 Installing from requirements.txt​

4.3 Advanced Requirements​

5. Best Practices​

5.1 Project Structure​

5.2 .gitignore for Python Projects​

5.3 Naming Conventions​

6. Working with Multiple Python Versions​

Using Specific Python Version​

7. Alternative Tools​

7.1 virtualenv (More Features)​

7.2 pipenv (pip + venv Combined)​

7.3 conda (Anaconda/Miniconda)​

8. Practical Workflow​

Starting a New Project​

Cloning an Existing Project​

9. Troubleshooting​

Activation Script Execution Policy (Windows)​

Can't Find Python​

Package Installation Fails​

10. Docker Alternative​

11. Comparison Table​

Summary​

Next Steps​

Practice Exercises​