Flask Fix, Crash & Optimization Guide

Flask is a lightweight Python web micro-framework built on Werkzeug and Jinja2. It gives you routing, request handling, and templating with minimal boilerplate, making it popular for APIs and small to mid-size services.

Install / First Setup

Install and create a minimal app:

pip install flask

# app.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, World!"

if __name__ == "__main__":
    app.run(debug=True)

Run it with flask run (after setting FLASK_APP=app.py) or python app.py. Always use a virtual environment (python -m venv .venv) to isolate dependencies.

Common Issues & Fixes

"Address already in use" (port 5000)

Cause: Another process (often macOS AirPlay on 5000, or a previous Flask run) holds the port. Fix: Run on another port: flask run -p 5001 or app.run(port=5001). On macOS, disable/relocate the AirPlay receiver conflicting with 5000.

"Could not import 'app'" / "FLASK_APP not set"

Cause: The FLASK_APP environment variable isn't set, or the file/module name is wrong. Fix: Set it: export FLASK_APP=app.py (macOS/Linux) or set FLASK_APP=app.py (Windows cmd), then flask run. With the if __name__ == '__main__' block you can also just python app.py.

Templates not found (Jinja2 TemplateNotFound)

Cause: Template files aren't in the expected templates/ folder next to the app, or template_folder was changed. Fix: Put .html files under a templates/ directory at the app root, or pass template_folder= explicitly when creating Flask(__name__).

Debug mode / Werkzeug warning

Cause: Running with debug=True in an unsafe context, or a Werkzeug version mismatch. Fix: Keep debug=True for local dev only. If a Werkzeug import error appears, reinstall pinned compatible versions (pip install -r requirements.txt).

404 on a defined route

Cause: Route decorator path mismatch, or trailing slash semantics (/foo vs /foo/). Fix: Match exact paths; Flask treats /foo/ and /foo as distinct by default. Use url_for() to generate links instead of hardcoding.

Performance & Optimization

• Low-End (4–8 GB RAM): The dev server (flask run) is single-process and for development only. Use it locally; keep dependencies minimal.
• Mid (16 GB): For production, serve with Gunicorn (gunicorn -w 4 app:app) behind Nginx. Enable caching for static responses and use Flask-Caching for expensive views.
• Workstation (32 GB+): Run multiple Gunicorn workers (-w ≈ 2×CPU cores + 1), put a reverse proxy in front, and offload static files to Nginx/CDN. Use async workers (gevent/eventlet) for I/O-heavy APIs.

Optimize by minimizing per-request work, using g/connection pools for DB access, and enabling Gzip/compression at the proxy.

Version & Compatibility Notes

• Flask 3.x requires Python 3.8+ (newer minors may require higher; verify against your installed version).
• The dev server is not for production — use Gunicorn/uWSGI. Werkzeug is the underlying WSGI library; pin compatible versions in requirements.txt.
• For exact version/Python requirements, consult official release notes.

FAQ

Q: How do I change the Flask port? A: Use flask run -p 5001 or app.run(port=5001). The default is 5000.

Q: Why does Flask say FLASK_APP is not set? A: You must tell Flask which module to load. Set FLASK_APP=app.py (adjust the filename) before flask run.

Q: Is the Flask dev server production-ready? A: No. Use Gunicorn or uWSGI behind a reverse proxy for production traffic.

Q: Why am I getting TemplateNotFound? A: Place templates in a templates/ directory at the app root, or set template_folder to the correct path.

Q: How many Gunicorn workers should I use? A: A common starting point is (2 × CPU cores) + 1, then tune based on load and memory.

Q: How do I enable debug mode safely? A: Set debug=True only in local development. Never enable it in production — it exposes an interactive debugger.

Related Guides

• Django Fix & Optimization Guide
• FastAPI Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Flask documentation.