Flask Application Factory Pattern: Benefits, Example, and Pitfalls

Use the Flask application factory to create configurable apps

Start by defining a create_app() function that returns a configured Flask instance. This lets you create separate apps for development, testing, and production without global state.

Worked example

# project/__init__.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_login import LoginManager

db = SQLAlchemy()
login_manager = LoginManager()

def create_app(config_object='project.config.DevelopmentConfig'):
    app = Flask(__name__)
    app.config.from_object(config_object)

    # Initialize extensions
    db.init_app(app)
    login_manager.init_app(app)
    login_manager.login_view = 'auth.login'

    # Register blueprints
    from project.auth import auth as auth_blueprint
    app.register_blueprint(auth_blueprint)

    from project.main import main as main_blueprint
    app.register_blueprint(main_blueprint)

    # Shell context for flask shell
    @app.shell_context_processor
    def make_shell_context():
        return {'db': db, 'app': app}

    return app

Place the factory in project/__init__.py so that flask run can discover it by setting the environment variable:

• export FLASK_APP=project
• export FLASK_ENV=development
• flask run

When the factory is called, Flask loads the configuration object, binds extensions via init_app(), and registers blueprints. Because the db and login_manager objects are created outside the factory, they are not tied to a specific app until init_app() runs inside create_app().

Limits and common mistakes

• Missing application context: accessing current_app or g outside a view or without pushing app.app_context() raises RuntimeError: Working outside of application context. Fix by wrapping code in with app.app_context(): or using flask shell which pushes a context automatically.
• Setting configuration after extension initialization: if you load config after calling db.init_app(app), the extension may use default values (e.g., SQLALCHEMY_DATABASE_URI) leading to connection errors. Load config before any init_app() calls.
• Circular imports: importing views or models that reference the app inside create_app() before the app is fully constructed can cause import loops. Keep those imports inside the function or use lazy loading (e.g., from . import models after db.init_app(app)).
• Extension state leakage: because extensions are initialized with init_app(), they should not retain state between app instances. Verify by creating two apps with different configs and checking that app.config['SQLALCHEMY_DATABASE_URI'] differs.

Practical verification

1. Run the factory: export FLASK_APP=project && flask run. The server should start without errors and serve the routes defined in the blueprints.
2. Check isolation: in a Python shell, from project import create_app; a1 = create_app('project.config.DevelopmentConfig'); a2 = create_app('project.config.TestingConfig'); print(a1.config['SECRET_KEY'] != a2.config['SECRET_KEY']) should output True.
3. Test context: with a1.app_context(): from flask import current_app; print(current_app.name) prints the app name, confirming the context is active.