⚙️ Configuration Management

Why Configuration Matters

Configuration is every value your app needs that isn't code: the database URL, the secret key, mail server credentials, feature flags, page sizes. The guiding principle comes from the Twelve-Factor App methodology: strictly separate config from code, and store anything that varies between deployments in the environment.

💡 Analogy: Think of config as the control panel bolted to the outside of a machine. The machine (your code) is sealed and identical everywhere; you change how it behaves by turning dials on the panel — never by cracking it open and rewiring the internals.

Done well, configuration lets you deploy the exact same artifact to every environment, keeps passwords out of your Git history, and makes testing trivial. Done poorly, it's the source of leaked credentials and "works on my machine" bugs.

The app.config Object

Flask exposes configuration as app.config, a dictionary subclass with a few extra loading helpers. You can read and write it like any dict:

# Writing values
app.config["SECRET_KEY"] = "change-me"
app.config.update(TESTING=True, SQLALCHEMY_DATABASE_URI="sqlite:///:memory:")

# Reading values (use .get() with a default to avoid KeyError)
key = app.config["SECRET_KEY"]
page_size = app.config.get("ITEMS_PER_PAGE", 20)

A handful of built-in keys control Flask itself. The most important ones:

Config Classes & Inheritance

The cleanest way to manage per-environment settings is a small hierarchy of classes: a Config base with shared defaults, and one subclass per environment that overrides just what differs. A dictionary maps names to classes so the factory can pick one.

# config.py
import os
from datetime import timedelta

class Config:
    """Shared defaults for every environment."""
    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-key-change-me")
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    REMEMBER_COOKIE_DURATION = timedelta(days=14)
    ITEMS_PER_PAGE = 20

    @staticmethod
    def init_app(app):
        """Hook for environment-specific setup (logging, folders, ...)."""
        pass


class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = os.environ.get(
        "DEV_DATABASE_URL", "sqlite:///dev.db"
    )


class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
    WTF_CSRF_ENABLED = False   # simplifies form tests


class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")
    SESSION_COOKIE_SECURE = True
    REMEMBER_COOKIE_SECURE = True


config = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "production": ProductionConfig,
    "default": DevelopmentConfig,
}

The factory loads a class by name with from_object, then runs its init_app hook:

# app/__init__.py
import os
from flask import Flask
from config import config

def create_app(config_name=None):
    app = Flask(__name__)

    config_name = config_name or os.environ.get("FLASK_CONFIG", "default")
    app.config.from_object(config[config_name])
    config[config_name].init_app(app)   # environment-specific setup

    # ... extensions, blueprints ...
    return app

Loading from the Environment

Flask can load config from several sources. The two you'll use most are from_object (classes, above) and pulling individual values from environment variables via os.environ.

python-dotenv for development

Typing export commands before every run is tedious. The python-dotenv package reads a local .env file into the environment automatically. Flask loads .env and .flaskenv on its own if python-dotenv is installed:

pip install python-dotenv

# .env  — NEVER commit this file
FLASK_CONFIG=development
SECRET_KEY=a-long-random-value
DEV_DATABASE_URL=sqlite:///dev.db
MAIL_USERNAME=you@example.com
MAIL_PASSWORD=super-secret

Because the config classes already read from os.environ, those values flow straight through — no extra wiring. If you need to load .env explicitly (e.g. in a script), call it before creating the app:

from dotenv import load_dotenv
load_dotenv()   # populate os.environ from .env

from app import create_app
app = create_app()

Secrets & Instance Folders

Secrets — API keys, database passwords, the secret key — must never be committed. Two mechanisms keep them out of your repo.

The instance folder

Flask supports an instance folder: a directory alongside your package that is meant to hold machine-specific, uncommitted config. Create the app with instance_relative_config=True and load an optional config.py from it:

app = Flask(__name__, instance_relative_config=True)
app.config.from_object(config["default"])
# silent=True -> no error if the file doesn't exist
app.config.from_pyfile("config.py", silent=True)

myapp/
├── app/            # your package (committed)
├── instance/
│   └── config.py   # secrets & local overrides (git-ignored)
└── config.py       # safe defaults (committed)

Lock it down with .gitignore

Belt and braces: ignore the secret files, and ship an example so teammates know what to fill in.

# .gitignore
.env
.flaskenv
instance/
*.pem
*.key

# .env.example  — committed as a template
FLASK_CONFIG=development
SECRET_KEY=
DATABASE_URL=
MAIL_USERNAME=
MAIL_PASSWORD=

Type-Safe Config with Pydantic

Plain app.config is an untyped dictionary — a missing value or a string where you expected an int fails deep inside a request. Pydantic Settings validates and coerces types at load time, so a bad config crashes immediately with a clear message.

pip install pydantic-settings

# settings.py  (Pydantic v2 style)
from pydantic import Field, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", case_sensitive=True)

    SECRET_KEY: str = Field(min_length=16)
    DEBUG: bool = False
    SQLALCHEMY_DATABASE_URI: str
    MAIL_PORT: int = 587
    MAIL_USE_TLS: bool = True

    @field_validator("SQLALCHEMY_DATABASE_URI")
    @classmethod
    def known_scheme(cls, v: str) -> str:
        if not v.startswith(("sqlite://", "postgresql://", "postgresql+psycopg://", "mysql://")):
            raise ValueError("Unsupported database URL scheme")
        return v

# app/__init__.py
from flask import Flask
from settings import Settings

def create_app():
    app = Flask(__name__)
    settings = Settings()            # reads env / .env, validates types
    app.config.update(settings.model_dump())
    # ... extensions, blueprints ...
    return app

Validate at Startup

Even without Pydantic, a few lines in the factory catch the most dangerous misconfigurations before they cause damage. The principle is fail fast: a clear error at boot beats a mysterious 500 in production.

def validate_config(app):
    """Refuse to start with dangerous or missing settings."""
    if not app.config.get("SQLALCHEMY_DATABASE_URI"):
        raise RuntimeError("SQLALCHEMY_DATABASE_URI is required")

    if not app.debug and not app.testing:
        if app.config["SECRET_KEY"] in (None, "", "dev-key-change-me"):
            raise RuntimeError("Refusing to run in production with a default SECRET_KEY")
        if not app.config.get("SESSION_COOKIE_SECURE"):
            app.logger.warning("SESSION_COOKIE_SECURE should be True in production")


def create_app(config_name=None):
    app = Flask(__name__)
    # ... load config ...
    validate_config(app)
    # ... extensions, blueprints ...
    return app

RuntimeError: Refusing to run in production with a default SECRET_KEY

That single guard has stopped countless accidental deploys with a placeholder key. Validation turns a silent security hole into a loud, obvious failure you fix in seconds.

Hands-on Exercise

# config.py
import os

class Config:
    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-key-change-me")
    SQLALCHEMY_TRACK_MODIFICATIONS = False

class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = os.environ.get("DEV_DATABASE_URL", "sqlite:///dev.db")

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")
    SESSION_COOKIE_SECURE = True

config = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "production": ProductionConfig,
    "default": DevelopmentConfig,
}

# app/__init__.py
import os
from flask import Flask
from config import config

def create_app(config_name=None):
    app = Flask(__name__)
    config_name = config_name or os.environ.get("FLASK_CONFIG", "default")
    app.config.from_object(config[config_name])
    validate_config(app)
    return app

def validate_config(app):
    if not app.config.get("SQLALCHEMY_DATABASE_URI"):
        raise RuntimeError("SQLALCHEMY_DATABASE_URI is required")

# .env.example
FLASK_CONFIG=development
SECRET_KEY=
DATABASE_URL=

Best Practices

Summary & Quiz

📚 Further Reading

• Flask Docs — Configuration Handling
• The Twelve-Factor App — Config
• Pydantic Settings Documentation

🚀 What's Next?

With factories, blueprints, and configuration under your belt, you're ready to build real APIs. Next: Flask-RESTful Extension, which adds structured, class-based resources for clean REST endpoints.