Flask Blueprints: Splitting an App Before It Becomes One Enormous File

A Flask blueprint is a group of routes, templates, static files and error handlers that you define separately and register onto an application. It is how you get out of a 2,000-line app.py without rewriting anything — the route functions are unchanged, only the decorator and the registration move.

Flask’s single-file start is genuinely one of its best features. It is also the thing that produces an unmaintainable module about four months later, when routes for authentication, the API, the admin panel and the public site are all in one file with a shared set of imports at the top.

Blueprints are the standard answer, and the migration is smaller than it looks.

What a blueprint actually is
The application factory
The url_for change that breaks templates
Templates, static files and per-blueprint hooks
Nesting, and where blueprints stop helping
How this fits the rest of the stack
FAQ

What a blueprint actually is

A blueprint records operations to perform on an application later. Defining one does nothing on its own; registering it applies everything it recorded.

# app/auth/__init__.py
from flask import Blueprint

bp = Blueprint('auth', __name__, url_prefix='/auth')

from app.auth import routes  # noqa: E402

The first argument is the blueprint’s name, which becomes the namespace for endpoints. The second is the import name, which Flask uses to locate the blueprint’s templates and static folder.

Routes use @bp.route rather than @app.route, and are otherwise identical:

# app/auth/routes.py
from flask import render_template, redirect, url_for
from app.auth import bp

@bp.route('/login', methods=['GET', 'POST'])
def login():
    return render_template('auth/login.html')

@bp.route('/logout')
def logout():
    return redirect(url_for('main.index'))

With url_prefix='/auth', that login route serves at /auth/login. The prefix is set once at registration rather than repeated on every decorator, which is one of the more immediately useful benefits.

The application factory

Blueprints work best with a factory function rather than a module-level app object. The factory creates the application, so you can build one with test configuration and one with production configuration in the same process.

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

def create_app(config_class='config.Config'):
    app = Flask(__name__)
    app.config.from_object(config_class)

    db.init_app(app)
    migrate.init_app(app, db)

    from app.auth import bp as auth_bp
    app.register_blueprint(auth_bp)

    from app.api import bp as api_bp
    app.register_blueprint(api_bp, url_prefix='/api/v1')

    from app.main import bp as main_bp
    app.register_blueprint(main_bp)

    return app

Blueprint imports go inside the factory. That is not stylistic — it is what breaks the circular import, since the blueprint modules import extensions that must exist before they are imported.

Extensions are instantiated in their own module without an app, then bound in the factory:

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

db = SQLAlchemy()
migrate = Migrate()

This is the piece that makes testing pleasant. Each test can build a fresh application against an in-memory database rather than mutating a global one.

The url_for change that breaks templates

This is the single most common thing to go wrong during a migration, and the error is clear once you know what it means.

Endpoints inside a blueprint are namespaced by the blueprint name. url_for('login') no longer resolves — it must be url_for('auth.login').

url_for('login')        # BuildError after the migration
url_for('auth.login')   # correct

Inside a template rendered from the same blueprint, a leading dot means “this blueprint”:

{{ url_for('.login') }}      <!-- relative to the current blueprint -->
{{ url_for('auth.login') }}  <!-- explicit, works anywhere -->

The relative form is convenient and makes a blueprint easier to rename. The explicit form is easier to grep for. Both are fine; pick one per project.

The failure is loud, which helps:

werkzeug.routing.exceptions.BuildError: Could not build url for endpoint 'login'.
Did you mean 'auth.login' instead?

Flask’s suggestion is usually correct. Sweep the templates for bare endpoint names when you migrate:

grep -rn "url_for('" app/templates/ | grep -v "url_for('\.\|url_for('static'"

Templates, static files and per-blueprint hooks

A blueprint can carry its own templates and static files, which is what makes it a genuinely reusable component:

bp = Blueprint(
    'admin', __name__,
    url_prefix='/admin',
    template_folder='templates',
    static_folder='static',
    static_url_path='/admin/static',
)

Flask searches the application’s template folder first, then each blueprint’s. So a blueprint template can be overridden by the application without editing the blueprint — useful for packaged components, and a source of confusion when two blueprints define index.html.

Namespace them in subdirectories to avoid that entirely: templates/admin/index.html, referenced as render_template('admin/index.html').

Blueprints also carry their own hooks and error handlers, which is where a lot of their value is:

@bp.before_request
def require_admin():
    if not current_user.is_authenticated or not current_user.is_admin:
        abort(403)

@bp.errorhandler(403)
def forbidden(e):
    return render_template('admin/403.html'), 403

That before_request runs for every route in the admin blueprint and nowhere else. Access control for a whole section becomes four lines in one place rather than a decorator you have to remember on every new route.

Nesting, and where blueprints stop helping

Flask 2.0 added nested blueprints, which are useful for versioned APIs:

api_v1 = Blueprint('v1', __name__, url_prefix='/v1')
users = Blueprint('users', __name__, url_prefix='/users')

api_v1.register_blueprint(users)
app.register_blueprint(api_v1, url_prefix='/api')
# routes resolve at /api/v1/users/...
# endpoint name is 'v1.users.list_users'

The endpoint names concatenate, which gets long quickly. Two levels is comfortable; three is usually a sign the structure wants rethinking.

Two honest limits worth knowing:

Blueprints cannot be unregistered. Registration is one-way for the life of the application object. If you need to swap components at runtime, this is not the mechanism.
A blueprint is not a service boundary. It organises code within one process. It does not give you independent deployment, separate scaling, or fault isolation.

That second point is worth being clear about, because blueprints are sometimes described as making an app modular in a stronger sense than they do. They make a codebase navigable. Splitting the deployment is a different decision with different costs, and it is usually premature.

How this fits the rest of the stack

Blueprints are a structural change that costs almost nothing and pays off steadily — the routes are unchanged, the imports move, and the file you were afraid to open becomes six files you can reason about. That is a good trade at almost any size.

What does not change is what the app needs to run: a WSGI server, a database, environment variables for the secrets, and somewhere for the logs to go. RunxBuild deploys Python applications from a GitHub repository with build logs, a live route, environment variables and a managed Postgres or MySQL alongside, so the structure of the code and the shape of the deployment stay independent decisions. The RunxBuild hosting calculator shows what the service and database come to together.

Useful related references:

FAQ

What is a Flask blueprint for?

It groups related routes, templates, static files and error handlers into a component you register onto an application. It is the standard way to split a growing app.py into navigable modules without changing the route functions themselves — only the decorator and the registration move.

Why does url_for stop working after adding blueprints?

Endpoints inside a blueprint are namespaced by its name, so url_for('login') becomes url_for('auth.login'). Inside a template rendered from the same blueprint, a leading dot — url_for('.login') — refers to the current blueprint. Flask’s BuildError usually suggests the correct name.

How do I avoid circular imports with Flask blueprints?

Use an application factory and import the blueprints inside the factory function rather than at module level. Instantiate extensions in a separate module without an app, then bind them with init_app in the factory. That ordering is what breaks the cycle.

Can blueprints be nested?

Yes, since Flask 2.0 — register one blueprint on another before registering the parent on the app. Endpoint names concatenate, so v1.users.list_users. Two levels works well for versioned APIs; three usually means the structure needs rethinking.

Are blueprints the same as microservices?

No. Blueprints organise code within a single process and a single deployment. They give you no independent scaling, deployment or fault isolation. Splitting a service is a separate decision with real operational costs, and blueprints are usually the better answer for a long time first.