Installation & Setup

Difficulty: Beginner

Setting up a proper Flask development environment is crucial for a maintainable project. Python's packaging ecosystem provides all the tools you need, and following best practices from the start will save you from dependency conflicts and deployment headaches.

The first step is always to create a virtual environment. A virtual environment is an isolated Python installation that keeps your project's dependencies separate from your system Python and other projects. Without a virtual environment, installing Flask globally could conflict with other Python applications on your machine that need different versions of the same packages.

Python 3 ships with the venv module, so you do not need to install anything extra. You create a virtual environment with 'python -m venv venv', which creates a directory called 'venv' containing a copy of the Python interpreter and a fresh pip installation. You activate it with 'source venv/bin/activate' on macOS/Linux or 'venv\Scripts\activate' on Windows. Once activated, your terminal prompt changes to show (venv), and any pip install commands will install packages into this isolated environment.

With the virtual environment active, you install Flask with 'pip install flask'. This also installs Flask's dependencies: Werkzeug, Jinja2, MarkupSafe, ItsDangerous, Click, and Blinker. Each serves a specific purpose: Werkzeug for WSGI utilities, Jinja2 for templating, MarkupSafe for safe string handling, ItsDangerous for cryptographic signing (used in sessions), Click for the flask command-line interface, and Blinker for signal support.

A well-organized Flask project follows a predictable structure. For small applications, a single file (app.py or main.py) in the project root works fine. For larger applications, you should use the application factory pattern with a package structure. The standard layout places your Flask package in a directory named after your project, with __init__.py containing the create_app factory function, separate modules for routes (views), models, forms, and configuration.

Managing dependencies is essential. After installing your packages, run 'pip freeze > requirements.txt' to capture all installed packages and their exact versions. This file allows anyone to reproduce your environment with 'pip install -r requirements.txt'. For more sophisticated dependency management, consider using pip-tools, Poetry, or PDM, which separate direct dependencies from transitive dependencies and provide lock files for deterministic builds.

Environment variables play a key role in Flask configuration. The FLASK_APP variable tells the flask command where your application is. The FLASK_ENV variable (deprecated in Flask 2.3 in favor of FLASK_DEBUG) controls the environment. You can use a .env file with python-dotenv to load these automatically. Never commit your .env file to version control, as it often contains secrets like database URLs and API keys.

The flask command-line tool provides useful commands out of the box. 'flask run' starts the development server, 'flask shell' opens an interactive Python shell with the application context, and 'flask routes' lists all registered URL rules. You can also define custom CLI commands using Click decorators.

Code examples

Creating a Virtual Environment

# Create virtual environment
python -m venv venv

# Activate on macOS/Linux
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate

# Install Flask
pip install flask

# Verify installation
python -c "import flask; print(flask.__version__)"

Always use a virtual environment for Flask projects. This isolates your dependencies and prevents conflicts between projects. The venv module is included with Python 3.3+ so no extra installation is needed.

Project Structure for Small Apps

# Simple project structure
my_flask_app/
    venv/
    app.py
    requirements.txt
    .env
    static/
        css/
        js/
        images/
    templates/
        base.html
        index.html

For small applications, a single app.py file with separate static/ and templates/ directories is sufficient. Flask looks for templates in a 'templates' folder and static files in a 'static' folder by default.

Project Structure for Larger Apps

# Package-based project structure
my_project/
    venv/
    requirements.txt
    config.py
    run.py
    app/
        __init__.py      # create_app factory
        models.py         # database models
        views/
            __init__.py
            main.py       # main blueprint
            auth.py       # auth blueprint
            api.py        # API blueprint
        forms.py          # WTForms
        templates/
            base.html
            main/
            auth/
        static/
            css/
            js/

Larger applications benefit from a package structure with blueprints. The create_app factory function in __init__.py initializes the app, registers blueprints, and configures extensions. This pattern supports testing with different configurations.

Managing Dependencies

# Save current dependencies
pip freeze > requirements.txt

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

# Example requirements.txt
# flask==3.1.0
# flask-sqlalchemy==3.1.1
# flask-login==0.6.3
# python-dotenv==1.0.1
# gunicorn==22.0.0

# Using .env file for configuration
# .env
# FLASK_APP=app.py
# FLASK_DEBUG=1
# SECRET_KEY=your-secret-key-here
# DATABASE_URL=sqlite:///app.db

requirements.txt pins exact versions to ensure reproducible builds. The .env file stores environment variables loaded by python-dotenv. Never commit .env to version control as it contains secrets.

Key points

Concepts covered

pip, Virtual Environments, venv, Project Structure, Requirements, Dependencies