Flask Environment and Installation

Introduction

Flask runs inside a Python virtual environment so project dependencies stay isolated from system Python. This chapter creates a venv, installs Flask 3, sets FLASK_APP, lays out a starter project folder, and adds a .gitignore so secrets and caches never enter Git.

Prerequisites

Create a Virtual Environment

Choose a project folder:

bash
mkdir flask-hello
cd flask-hello

Create venv:

bash
python -m venv .venv

Activate:

OSCommand
macOS / Linuxsource .venv/bin/activate
Windows (cmd).venv\Scripts\activate.bat
Windows (PowerShell).venv\Scripts\Activate.ps1

Prompt shows (.venv) when active.

Upgrade pip:

bash
python -m pip install -U pip

Code explanation:

  • venv keeps Flask and other packages in .venv/ only for this project
  • Deactivate later with deactivate

See also pip and uv on this site.

Install Flask

bash
pip install "Flask>=3.0,<4" python-dotenv

Pin versions for reproducibility:

bash
pip freeze > requirements.txt

Example requirements.txt:

text
Flask==3.0.3
python-dotenv==1.0.1

Verify:

bash
python -c "import flask; print(flask.__version__)"

Expected: 3.x.x.

Project Layout

Recommended starter structure:

text
flask-hello/
├── .venv/
├── .env                 # local secrets — do not commit
├── .gitignore
├── requirements.txt
├── app.py               # small tutorials start here
└── instance/            # optional local overrides (gitignored)

Later chapters move to:

text
flask-hello/
├── app/
│   ├── __init__.py      # create_app factory
│   ├── routes.py
│   ├── templates/
│   └── static/
└── tests/

.gitignore

gitignore
.venv/
__pycache__/
*.py[cod]
.env
instance/
.pytest_cache/
dist/
*.egg-info/

See Git .gitignore patterns for Node/Java comparisons.

Warning

Never Commit .env

Database URLs and SECRET_KEY belong in environment variables—not in Git history.

FLASK_APP Environment Variable

Tell the Flask CLI where your application lives.

Single-module app in app.py:

bash
export FLASK_APP=app

On Windows PowerShell:

powershell
$env:FLASK_APP = "app"

Factory pattern (later):

bash
export FLASK_APP=app:create_app

Optional development flags:

bash
export FLASK_DEBUG=1

Code explanation:

  • flask run reads FLASK_APP to import your app object or factory

Editor Setup

  • VS Code: select Python interpreter from .venv/bin/python
  • PyCharm: Project Interpreter → Add → Existing venv

Run/debug configuration can call flask run or python app.py.

Verify End-to-End

After chapter 3 you will run the server; for now confirm imports:

bash
python -c "from flask import Flask; print('OK')"

FAQ

python vs python3?

On Linux/macOS use python3 if python points to Python 2 (rare today). Inside venv, python is correct.

pip install fails?

Upgrade pip; check network/proxy; use mirror if needed.

Global pip install Flask?

Avoid—always use venv per project.

Wrong Flask version?

pip install "Flask>=3.0,<4" --force-reinstall

WSL2 on Windows?

Same Linux venv commands; browser on Windows hits http://127.0.0.1:5000.

requirements.txt vs pyproject.toml?

Both valid—this track uses requirements.txt for simplicity.