Virtual Environments Setup — Practical Guide for CS50 Web Programming

"Your project is not just code — it's a tiny ecosystem. Treat it like one."

You're already comfortable with installing Python and Node, you know the value of version control, and your linting game is sharpening up (beautiful code is moral code). Now we move from "I have Python" to "I have a safe, reproducible workspace for each project." Welcome to virtual environments — the portable little bubbles that keep your projects from poisoning each other.

Why virtual environments? (The problem they solve)

• Dependency isolation: different projects often need different versions of the same package. Without isolation, installing package A for Project 1 could break Project 2.
• Reproducibility: you can share the exact list of packages so others (or your future self) can recreate the environment.
• Safety: avoid messing with system Python (which package managers and the OS might depend on).

Analogy: imagine each project is a house with its own wardrobe. Virtual environments let each house have its own closet so outfits (packages) don’t get stolen by roommates.

Quick taxonomy: venv, virtualenv, pipenv, conda (cheat-sheet)

For CS50 web programming, use the builtin venv (simplicity + portability). If you like Pipenv, it's fine — but know the differences.

Standard workflow (recommended for CS50 projects)

1. Create a project folder and git repo.
2. Create a virtual environment in the project folder.
3. Activate it.
4. Install packages (Flask, requests, linters, etc.).
5. Freeze dependencies to requirements.txt and commit that file (not the venv).
6. Add the venv and secrets (.env) to .gitignore.

This ties into version control concepts: commit the recipe (requirements.txt), not the kitchen (the venv folder). You learned why in Orientation > Version control concepts — exact dependencies are what you track.

Commands — create, activate, install, export

macOS / Linux (bash, zsh)

# create a venv named .venv (dot-leading makes it hidden in many UIs)
python3 -m venv .venv

# activate it
source .venv/bin/activate

# install packages
pip install flask

# save installed packages
pip freeze > requirements.txt

# later, recreate
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows (PowerShell)

# create
python -m venv .venv

# activate (PowerShell)
.\.venv\Scripts\Activate.ps1

# cmd.exe activate
.\.venv\Scripts\activate.bat

Notes

• Use python3 if your system maps python to Python 2. If python is Python 3, that's fine.
• Use .venv (or env, venv) — be consistent across projects.

What to put in .gitignore (and what not to)

Example .gitignore entries:

# Virtual environment
.venv/

# Python cache
__pycache__/
*.py[cod]

# Secrets
.env

# Editor files
.vscode/
.idea/

Why: venv folders are large, machine-specific, and unnecessary in the repo. Instead, commit requirements.txt so others can recreate the environment.

requirements.txt vs Pipfile / Pipfile.lock

• requirements.txt is simple and universal: it lists packages and exact versions (often produced by pip freeze).
• Pipfile and Pipfile.lock are from Pipenv: they separate dev vs prod and provide deterministic installs. Fine to use if you understand them.

For CS50, requirements.txt keeps things straightforward and compatible with most deployment systems.

Development dependencies and linting

Install your linters and formatters inside the virtual environment so the project is self-contained:

pip install black flake8
pip freeze > requirements.txt  # or requirements-dev.txt

You can maintain two files: requirements.txt (runtime) and requirements-dev.txt (linters, test frameworks). This keeps production installs lean.

Tieback: remember the coding style & linting lesson? Install those tools in the venv so CI systems and collaborators run the same versions.

VS Code, interpreters, and common gotchas

• In VS Code press Ctrl+Shift+P → "Python: Select Interpreter" and pick .venv/bin/python (or the Windows path). That ensures the editor runs linters and the debugger inside the venv.
• If activation fails, check: is python / python3 pointing to the expected Python? Use python --version.
• On macOS, if you installed Python from the store vs Homebrew vs system, the paths differ — again, use the explicit python3 -m venv .venv form.

Extra tools worth knowing (short mentions)

• pipx: install command-line Python tools globally but isolated (good for black, httpie as CLI tools).
• pyenv: manage multiple Python versions on your machine; useful if you need to run Python 3.8 and 3.11 side-by-side.

These are optional but powerful for advanced workflows.

Troubleshooting quick hits

• "I installed a package but it's not available": make sure the venv is activated in the terminal you used.
• "Different package versions on two machines": run pip freeze > requirements.txt and have the other person pip install -r requirements.txt.
• "Committing everything": check .gitignore — remove the venv from git with git rm -r --cached .venv then commit.

Key takeaways (TL;DR)

• Use venv (python3 -m venv .venv) for CS50 projects: simple, reliable, reproducible.
• Activate the environment before installing packages. Freeze to requirements.txt and commit that file, not the venv.
• Add .venv/ and .env to .gitignore to avoid clutter and leaking secrets.
• Install linters inside venv so everyone uses the same tooling versions.

This is the moment where the concept finally clicks: a virtual environment is your project's private wardrobe. Keep the socks separate. Keep the code running.

If you want, I can provide a starter repository template (README, .gitignore, venv hints, sample requirements.txt, and a little Flask "Hello CS50" app) so you can clone and start coding in 60 seconds. Want that?