🏭 Application Factory Pattern

Why a Factory?

An application factory is simply a function — conventionally named create_app() — that constructs a Flask application, configures it, wires up its pieces, and returns it. Instead of one app created once at import time, you get a recipe you can run whenever you need a fresh, independently configured instance.

💡 Analogy: A global app is a single show-car welded together on the showroom floor — beautiful, but there's exactly one, and its options are fixed. A factory is the assembly line: give it a spec sheet (a config name) and it rolls out a car built to order — one tuned for development, another stripped down for the test track, a third hardened for production.

That ability to "build to order" is the whole point. Tests want a throwaway app pointed at an in-memory database; production wants secure cookies and a real Postgres URL; development wants the debugger on. One function, many apps.

The Trouble with a Global App

Here's the pattern almost every tutorial starts with. Nothing is wrong with it — until your project outgrows a single file.

from flask import Flask

# A single, global application instance
app = Flask(__name__)
app.config["SECRET_KEY"] = "your-secret-key"
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///site.db"

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

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

Four real problems emerge as this grows:

Your First Factory

The core move is to wrap app creation in a function. Everything that used to live at module scope now happens inside create_app().

# app/__init__.py
from flask import Flask

def create_app(config=None):
    """Build and return a configured Flask application."""
    app = Flask(__name__)

    # Sensible defaults
    app.config.from_mapping(
        SECRET_KEY="dev",
        SQLALCHEMY_DATABASE_URI="sqlite:///dev.db",
    )

    # Override with anything the caller passed in
    if config is not None:
        app.config.from_mapping(config)

    @app.route("/")
    def home():
        return "Hello from the application factory!"

    return app

Now the same code produces different apps depending on what you hand it:

# A test app pointed at a disposable in-memory database
test_app = create_app({
    "TESTING": True,
    "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
})

# A production app with a real database and a strong key
prod_app = create_app({
    "SECRET_KEY": "loaded-from-a-secret-manager",
    "SQLALCHEMY_DATABASE_URI": "postgresql+psycopg://user:pass@db/prod",
})

Deferred Extension Init

Extensions like Flask-SQLAlchemy support a two-step lifecycle designed exactly for factories. You create the extension object once, at module level, with no app, then bind it to each app inside the factory with init_app(). Because the extension object exists independently, any module can import it without importing the app.

# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager

# Created empty — not yet bound to any app
db = SQLAlchemy()
migrate = Migrate()
login_manager = LoginManager()
login_manager.login_view = "auth.login"

# app/__init__.py
from flask import Flask
from app.extensions import db, migrate, login_manager

def create_app(config=None):
    app = Flask(__name__)
    app.config.from_mapping(SECRET_KEY="dev",
                            SQLALCHEMY_DATABASE_URI="sqlite:///dev.db")
    if config:
        app.config.from_mapping(config)

    # Bind each extension to THIS app instance
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)

    return app

Models import db from app.extensions — never from the app package — so there is no cycle. With SQLAlchemy 2.0, models use the typed Mapped / mapped_column style:

# app/models.py
from datetime import datetime, timezone
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from app.extensions import db

class Task(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100))
    completed: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )

    def __repr__(self) -> str:
        return f"<Task {self.title!r}>"

Anything that needs a live app — like creating tables — runs inside an application context, because db needs to know which app (and therefore which database) it's talking to:

from app import create_app
from app.extensions import db

app = create_app()
with app.app_context():
    db.create_all()   # now db knows which database URI to use

Wiring Blueprints, Errors & CLI

The factory is also the natural home for registering blueprints, error handlers, and custom command-line commands. Keeping this wiring in one function makes the shape of the whole app easy to read.

Blueprints

Blueprints group related routes into modules (the next lesson covers them in depth). Register them inside the factory:

from app.blueprints.main import main
from app.blueprints.auth import auth

def create_app(config=None):
    app = Flask(__name__)
    # ... config + extensions ...
    app.register_blueprint(main)
    app.register_blueprint(auth, url_prefix="/auth")
    return app

Error handlers

Centralize custom error pages so every route shares them:

from flask import render_template

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

    @app.errorhandler(404)
    def not_found(error):
        return render_template("errors/404.html"), 404

    @app.errorhandler(500)
    def server_error(error):
        return render_template("errors/500.html"), 500

    return app

Custom CLI commands

Flask uses Click for its command line. A factory can attach app-specific commands like flask init-db:

import click
from app.extensions import db

def create_app(config=None):
    app = Flask(__name__)
    # ... setup ...

    @app.cli.command("init-db")
    @click.option("--drop", is_flag=True, help="Drop tables first.")
    def init_db(drop):
        """Create database tables."""
        if drop:
            db.drop_all()
        db.create_all()
        click.echo("Database initialized.")

    return app

$ flask init-db
Database initialized.

$ flask init-db --drop
Database initialized.

A Complete, Modern Factory

Put together, a real project keeps concerns in separate modules and lets the factory stitch them into a whole. Here's a clean layout for a blog app:

myapp/
├── app/
│   ├── __init__.py        # create_app() lives here
│   ├── config.py          # config classes per environment
│   ├── extensions.py      # db, migrate, login_manager
│   ├── models.py          # SQLAlchemy 2.0 models
│   └── blueprints/
│       ├── main.py
│       ├── auth.py
│       ├── blog.py
│       └── errors.py
├── tests/
│   └── conftest.py
└── wsgi.py                # entry point for gunicorn / flask run

The factory reads a configuration class (covered fully in the Configuration Management lesson) and assembles everything:

# app/__init__.py
import os
from flask import Flask
from app.config import config
from app.extensions import db, migrate, login_manager

def create_app(config_name=None):
    """Create and configure the Flask application."""
    app = Flask(__name__)

    # Pick a config class by name (defaults to $FLASK_CONFIG or 'default')
    config_name = config_name or os.environ.get("FLASK_CONFIG", "default")
    app.config.from_object(config[config_name])

    # Bind extensions to this app
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)

    # Register blueprints
    from app.blueprints.main import main
    from app.blueprints.auth import auth
    from app.blueprints.blog import blog
    from app.blueprints.errors import errors
    app.register_blueprint(main)
    app.register_blueprint(auth, url_prefix="/auth")
    app.register_blueprint(blog, url_prefix="/blog")
    app.register_blueprint(errors)

    # Handy shell context: `flask shell` gets db + models pre-imported
    @app.shell_context_processor
    def shell_context():
        from app.models import User, Post
        return {"db": db, "User": User, "Post": Post}

    return app

# wsgi.py — what gunicorn or `flask run` imports
from app import create_app

app = create_app()

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

Testing with the Factory

This is where the pattern pays for itself. Because create_app() can build a fresh, isolated app on demand, each test run gets a clean database and no shared state. Pytest fixtures make it tidy:

# tests/conftest.py
import pytest
from app import create_app
from app.extensions import db

@pytest.fixture
def app():
    """A fresh app + empty in-memory database for each test."""
    app = create_app("testing")   # TESTING=True, sqlite:///:memory:
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    """A test client that issues fake requests without a real server."""
    return app.test_client()

@pytest.fixture
def runner(app):
    """A runner for testing custom CLI commands."""
    return app.test_cli_runner()

# tests/test_main.py
def test_home_page(client):
    response = client.get("/")
    assert response.status_code == 200
    assert b"Hello" in response.data

Hands-on Exercise

# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()

# app/models.py
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from app.extensions import db

class Task(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100))

# app/__init__.py
from flask import Flask
from app.extensions import db

def create_app(config=None):
    app = Flask(__name__)
    app.config.from_mapping(SQLALCHEMY_DATABASE_URI="sqlite:///dev.db")
    if config:
        app.config.from_mapping(config)
    db.init_app(app)

    from app import models  # register the model

    @app.route("/")
    def index():
        return "OK"

    return app

# tests/conftest.py
import pytest
from app import create_app
from app.extensions import db

@pytest.fixture
def client():
    app = create_app({"TESTING": True,
                      "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:"})
    with app.app_context():
        db.create_all()
        yield app.test_client()
        db.drop_all()

# tests/test_app.py
def test_index(client):
    assert client.get("/").status_code == 200

Best Practices

Summary & Quiz

📚 Further Reading

• Flask Docs — Application Factories
• Flask Tutorial — The Application Setup
• TestDriven.io — Flask Application Factory Pattern

🚀 What's Next?

You registered blueprints in the factory without really explaining them. Next up: Blueprints for Modular Applications — how to split a growing Flask app into clean, self-contained feature modules.