Python Virtual Environments Explained

Virtual environments are essential for Python development. They create isolated spaces for each project's dependencies, preventing conflicts and keeping your system clean. This guide covers everything from basic usage to advanced workflow tips.

Why Virtual Environments?

Imagine you have two Django projects: one needs Django 4.2, the other needs Django 5.1. Without virtual environments, you can only have one version installed globally. Virtual environments solve this by giving each project its own isolated set of packages.

Creating Virtual Environments

Using venv (Built-in, Python 3.3+)

# Create a virtual environment
python -m venv myproject_env

# Or simply call it 'venv' (most common convention)
python -m venv venv

# Activate it
# On Linux/macOS:
source venv/bin/activate

# On Windows (CMD):
venv\Scripts\activate.bat

# On Windows (PowerShell):
venv\Scripts\Activate.ps1

# Your prompt changes to show the active environment:
(venv) $ python --version

Using virtualenv (Third-party, more features)

# Install virtualenv
pip install virtualenv

# Create environment
virtualenv venv

# Create with specific Python version
virtualenv --python=python3.12 venv

Managing Packages

# Install packages (only in this environment)
pip install django
pip install django==5.1      # Specific version
pip install "django>=5.0"    # Minimum version

# See what's installed
pip list
pip freeze

# Save dependencies to a file
pip freeze > requirements.txt

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

# Upgrade a package
pip install --upgrade django

# Uninstall
pip uninstall django

The requirements.txt File

This file lists all your project's dependencies with exact versions:

# requirements.txt
Django==5.1
djangorestframework==3.15.2
psycopg2-binary==2.9.9
gunicorn==23.0.0
redis==5.0.8
Pillow==10.4.0

Deactivating and Deleting

# Deactivate the current environment
deactivate

# Delete the environment (just remove the folder)
rm -rf venv/

The .gitignore Rule

Never commit your virtual environment to Git. Add it to .gitignore:

# .gitignore
venv/
env/
.venv/
*.pyc
__pycache__/
.env

Complete Workflow Example

# 1. Create project
mkdir my_django_project && cd my_django_project

# 2. Create & activate virtual environment
python -m venv venv
source venv/bin/activate

# 3. Install packages
pip install django djangorestframework

# 4. Save requirements
pip freeze > requirements.txt

# 5. Initialize git
git init
echo "venv/" >> .gitignore

# 6. Start Django project
django-admin startproject config .

# 7. When done working
deactivate

Troubleshooting

Summary

Virtual environments are non-negotiable for Python development:

• Always create a venv for each project
• Activate before installing packages or running code
• Use requirements.txt to track dependencies
• Never commit the venv folder to Git
• Deactivate when switching projects