Flask Project Setup and venv — CS50 Style

"Your browser talks HTTP. Your Flask app answers. Your venv keeps the chaos in a jar."

---

You already learned how HTML, CSS, and JavaScript make pages look and behave, and how HTTP/REST gets the browser and the server speaking the same language. Now let's stop yelling across the network and set up a clean workspace on your computer to build a Flask web app — the CS50 way.

This guide walks you through project structure, creating and using a Python virtual environment (venv), installing dependencies, and the little developer niceties that make debugging and deploying less painful.

Why venv? (Short: It's hygiene)

• Isolation: Each project can have its own packages and versions. No more accidental global upgrades that break other projects.
• Reproducibility: A requirements.txt file plus a venv recreates the exact environment for others (or for you, three months later, bleary-eyed).
• Safety: Avoid installing packages globally with sudo. Your system Python stays happy.

In short: venv = tidy desk. No venv = coffee spills on everything.

---

Minimal project layout (recommended)

my-flask-app/
├─ venv/             # created by python -m venv (do not commit)
├─ app.py            # minimal Flask app (or package folder)
├─ requirements.txt  # frozen dependencies
├─ templates/        # HTML (Jinja2 templates)
├─ static/           # CSS, JS, images
└─ .gitignore

Put the venv inside the project folder for convenience, but add it to .gitignore so you don’t accidentally push it to GitHub.

---

Create a venv (cross-platform commands)

1. Make your project folder and cd into it:

mkdir my-flask-app
cd my-flask-app

2. Create the virtual environment (Python 3.6+).

python3 -m venv venv
# or on some systems just:
python -m venv venv

3. Activate it:

• macOS / Linux / WSL:

source venv/bin/activate

• Windows (PowerShell):

venv\Scripts\Activate.ps1

• Windows (cmd.exe):

venv\Scripts\activate.bat

When activated, your prompt should show (venv) — the little badge of responsibility.

4. Upgrade pip (optional but recommended):

pip install --upgrade pip setuptools wheel

---

Install Flask and other packages

While your venv is active:

pip install Flask
# plus any other packages you'll use, e.g.:
pip install requests sqlalchemy

Then freeze the exact versions:

pip freeze > requirements.txt

Now your repo contains a requirements.txt that others can use to reproduce your environment.

To reinstall later (or on another machine):

python -m venv venv  # create
source venv/bin/activate
pip install -r requirements.txt

---

Minimal Flask app example (app.py)

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/')
def index():
    return render_template('index.html')

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Notes:

• Flask's development server is great for learning and debugging. Do not use it in production.
• The app serves Jinja templates from templates/ and static files from static/ by convention — tying directly into the HTML/CSS/JS you learned earlier.

---

Environment variables (recommended for CS50 / dev comfort)

Use environment variables to tell Flask which file is your app and whether you want debug mode.

• macOS / Linux:

export FLASK_APP=app.py
export FLASK_ENV=development  # enables debug/reload (older Flask)
flask run

• Windows (PowerShell):

$env:FLASK_APP = "app.py"
$env:FLASK_ENV = "development"
flask run

Flask 2.2+ favors the FLASK_DEBUG and FLASK_APP combo and auto-reload. Alternatively use app.run(debug=True) in code for quick hacks, but environment variables keep config out of your source.

---

.gitignore essentials

Never commit the venv or environment-specific files. Example .gitignore lines:

venv/
__pycache__/
*.pyc
instance/
.env

If you use a .env file for secret keys locally, ignore it (and use actual secret storage in production).

---

Quick comparison: dev server vs production

Use case	What to run	Notes
Local development	flask run or python app.py	Hot reload, debugger, not secure for public use
Production (simple)	gunicorn app:app	WSGI server; pair with Nginx for static files

Remember: the built-in server is for learning and debugging only.

---

Debugging and productivity tips

• Activate the venv every time you work on the project.
• Recreate env from requirements.txt when switching machines.
• Use a linter or editor virtualenv integration (VS Code picks up venv/ automatically if workspace opened inside project).
• If you install a package and things break: check pip freeze, update requirements, and restart the dev server.

---

Why this matters for the full web stack

You already know how the browser requests HTML, CSS, JS and how client-side JS can call APIs. Flask is the server-side piece that creates those HTML pages, serves static assets, and exposes HTTP endpoints (REST-ish) for your JS to call. A clean project + venv means your server code runs consistently on any machine — which is critical when collaborating or deploying.

"A good venv is like a good roommate: it keeps its dishes in its own sink and doesn't change the locks without asking."

---

Key takeaways

• Always use a virtual environment (python -m venv venv). It isolates dependencies and makes your projects reproducible.
• Freeze dependencies with pip freeze > requirements.txt and recreate with pip install -r requirements.txt.
• Keep your venv and secrets out of GitHub (.gitignore).
• Use Flask's dev server for learning; use a WSGI server (gunicorn) + reverse proxy for production.
• Structure your project (app.py, templates/, static/) so your front-end work plugs straight into the server.

Go build something that uses HTML/CSS/JS from earlier modules — maybe a little to-do app where the frontend calls a Flask API to add items. You’ll connect everything you’ve learned: client-side interactivity, HTTP endpoints, and a tidy server environment that won’t leak dependencies all over your system.

Happy coding. Activate your venv. Then pretend you didn’t just create magic with 4 lines of code.