Virtual Environments

Virtual Environments

When you work on multiple Python projects, you quickly discover that different projects may require different versions of the same library. For example, one project might need Django 4.2 while another requires Django 5.0. Installing both globally would create conflicts. Virtual environments solve this problem by creating isolated Python installations for each project, with their own set of installed packages. Understanding virtual environments is essential for professional Python development and is a standard practice in the industry.

Creating Virtual Environments with venv

# Create a virtual environment (built into Python 3.3+)
python -m venv myproject_env

# Directory structure created:
# myproject_env/
# ├── bin/          (Scripts/ on Windows)
# │   ├── activate
# │   ├── python
# │   └── pip
# ├── include/
# ├── lib/
# │   └── python3.12/
# │       └── site-packages/
# └── pyvenv.cfg

# Activate the virtual environment
# On macOS/Linux:
source myproject_env/bin/activate

# On Windows:
# myproject_env\Scripts\activate

# Your prompt changes to show the active environment:
# (myproject_env) $

# Deactivate when done
deactivate

Managing Packages with pip

# Install packages (with venv activated)
pip install requests
pip install flask==3.0.0        # Specific version
pip install "django>=4.2,<5.0"  # Version range

# List installed packages
pip list

# Show package details
pip show requests

# Upgrade a package
pip install --upgrade requests

# Uninstall a package
pip uninstall requests

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

# Generate requirements file
pip freeze > requirements.txt

# Example requirements.txt content:
# flask==3.0.0
# requests==2.31.0
# sqlalchemy==2.0.23
# python-dotenv==1.0.0

Project Setup Best Practices

# Standard project structure
# my_project/
# ├── .gitignore
# ├── .env                  (environment variables — never commit)
# ├── requirements.txt      (production dependencies)
# ├── requirements-dev.txt  (development dependencies)
# ├── README.md
# ├── setup.py or pyproject.toml
# ├── app/
# │   ├── __init__.py
# │   ├── main.py
# │   └── utils.py
# ├── tests/
# │   ├── __init__.py
# │   └── test_main.py
# └── venv/                 (virtual environment — never commit)

# .gitignore should include:
# venv/
# __pycache__/
# *.pyc
# .env
# *.egg-info/
# dist/
# build/

# Setup script for new developers
# setup.sh
#!/bin/bash
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt
echo "Environment ready! Run: source venv/bin/activate"

Environment Variables with python-dotenv

# Install python-dotenv
# pip install python-dotenv

# .env file (never commit this!)
# DATABASE_URL=sqlite:///app.db
# SECRET_KEY=your-secret-key-here
# API_KEY=abc123def456
# DEBUG=True

# Load in your application
import os
from dotenv import load_dotenv

load_dotenv()  # Load .env file

database_url = os.getenv("DATABASE_URL", "sqlite:///default.db")
secret_key = os.getenv("SECRET_KEY")
debug = os.getenv("DEBUG", "False").lower() == "true"
api_key = os.getenv("API_KEY")

if not secret_key:
    raise ValueError("SECRET_KEY environment variable is required")

print(f"Database: {database_url}")
print(f"Debug mode: {debug}")

Alternative Tools

# pipenv — combines pip and virtualenv
# pip install pipenv
# pipenv install requests
# pipenv shell          # Activate environment
# Creates Pipfile and Pipfile.lock

# poetry — modern dependency management
# pip install poetry
# poetry new my-project
# poetry add requests
# poetry install
# Creates pyproject.toml and poetry.lock

# conda — popular in data science
# conda create -n myenv python=3.12
# conda activate myenv
# conda install numpy pandas

Pro tip: Always add your virtual environment directory (venv/) to .gitignore. Share your dependencies through requirements.txt, not the actual environment. Each developer and deployment target should create their own virtual environment from the requirements file.

Key Takeaways

• Virtual environments isolate project dependencies, preventing version conflicts between projects.
• Use python -m venv env_name to create and source env_name/bin/activate to activate a virtual environment.
• Use pip freeze > requirements.txt to capture dependencies and pip install -r requirements.txt to restore them.
• Store sensitive configuration in .env files and load them with python-dotenv — never commit secrets to version control.
• Modern alternatives like Poetry and Pipenv provide enhanced dependency management with lock files for reproducible builds.