🧩 Blueprints for Modular Applications

What Is a Blueprint?

A blueprint is a reusable collection of routes, templates, static files, and hooks that you define separately from the application and then register onto an app. It's Flask's built-in answer to the "separation of concerns" problem: instead of every view decorated with @app.route in one file, each feature area owns its own module.

💡 Analogy: Think of an architect's plans for a building. There's a separate blueprint for plumbing, one for electrical, one for the structure. Each is drawn on its own, but they all come together into a single building. A Flask blueprint is exactly that — a self-contained plan for one part of your app that gets assembled into the whole at registration time.

Crucially, a blueprint is not an app. It records what you want (routes, handlers) as a set of deferred operations, and only when you call app.register_blueprint() does Flask replay those operations onto the real application.

Creating & Registering

Creating a blueprint looks almost identical to creating an app, except you decorate views with the blueprint object instead of app.

# app/blueprints/main.py
from flask import Blueprint, render_template

# name -> used by url_for();  __name__ -> helps locate templates/static
main = Blueprint("main", __name__)

@main.route("/")
def index():
    return render_template("main/index.html")

@main.route("/about")
def about():
    return render_template("main/about.html")

The blueprint does nothing until it's registered onto an app — which, in a factory-based project, happens inside create_app():

# app/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)

    from app.blueprints.main import main
    app.register_blueprint(main)

    return app

You can pass options at creation time, at registration time, or both:

# Prefix set when creating the blueprint...
auth = Blueprint("auth", __name__, url_prefix="/auth")

# ...or when registering it (registration wins if both are set)
app.register_blueprint(auth, url_prefix="/account")

URL Prefixes & Nesting

Prefixes

A url_prefix is prepended to every route in the blueprint. With url_prefix="/auth", a view mapped to /login is served at /auth/login. This keeps each feature's URLs namespaced and collision-free.

auth = Blueprint("auth", __name__, url_prefix="/auth")

@auth.route("/login")     # -> /auth/login
def login():
    return render_template("auth/login.html")

@auth.route("/register")  # -> /auth/register
def register():
    return render_template("auth/register.html")

Nested blueprints

Modern Flask (1.2+) supports registering a blueprint onto another blueprint, which is perfect for versioned APIs. Prefixes compose from outer to inner:

# app/blueprints/api/v1.py
from flask import Blueprint, jsonify

api_v1 = Blueprint("v1", __name__, url_prefix="/v1")

@api_v1.route("/users")
def users():
    return jsonify(users=[])

# app/blueprints/api/__init__.py
from flask import Blueprint
from app.blueprints.api.v1 import api_v1

api = Blueprint("api", __name__, url_prefix="/api")
api.register_blueprint(api_v1)   # nesting: /api + /v1 + /users -> /api/v1/users

Linking with url_for

Because routes now live in namespaces, you reference them by blueprint_name.view_name. This is the single most important habit to build with blueprints — hard-coded URLs break the moment you change a prefix; url_for never does.

from flask import url_for

# Same blueprint
url_for("blog.show_post", post_id=42)   # -> /blog/post/42

# Another blueprint
url_for("auth.login")                   # -> /auth/login
url_for("main.index")                   # -> /

Inside templates the syntax is identical:

<a href="{{ url_for('auth.login') }}">Log in</a>
<a href="{{ url_for('blog.show_post', post_id=post.id) }}">{{ post.title }}</a>

Templates, Hooks & Errors

Blueprint templates

A blueprint can carry its own templates/ folder. Flask searches the app's template folder first, then each blueprint's. Namespacing templates in a subfolder (auth/login.html) avoids clashes between blueprints that both have an index.html.

admin = Blueprint("admin", __name__, template_folder="templates")

@admin.route("/users")
def users():
    # looks for templates/admin/users.html inside the blueprint,
    # then falls back to the app's template folder
    return render_template("admin/users.html")

Request hooks

Blueprints can run code before or after each of their requests — ideal for scoping a permission check to one area:

from flask import g, abort

@admin.before_request
def require_admin():
    """Runs before every admin route only."""
    if g.user is None or not g.user.is_admin:
        abort(403)

@admin.after_request
def add_header(response):
    response.headers["X-Admin"] = "1"
    return response

Error handlers: scoped vs. app-wide

This distinction trips up a lot of people. @bp.errorhandler handles errors raised inside that blueprint's routes. @bp.app_errorhandler registers an application-wide handler from within a blueprint — useful for putting your global 404/500 pages in a dedicated errors blueprint.

errors = Blueprint("errors", __name__)

@errors.app_errorhandler(404)   # applies to the WHOLE app
def page_not_found(error):
    return render_template("errors/404.html"), 404

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

Structuring a Real App

As projects grow you'll pick between two organizing philosophies.

For most real applications, divisional wins — each blueprint becomes a mini-package that owns its routes, models, and forms:

app/
├── __init__.py          # create_app()
├── extensions.py
├── config.py
└── blueprints/
    ├── main/
    │   ├── __init__.py   # Blueprint + `from . import routes`
    │   └── routes.py
    ├── auth/
    │   ├── __init__.py
    │   ├── routes.py
    │   ├── models.py
    │   └── forms.py
    └── blog/
        ├── __init__.py
        ├── routes.py
        ├── models.py
        └── forms.py

The lazy-import pattern in each package's __init__.py avoids circular imports: create the blueprint first, then import the routes that decorate it.

# app/blueprints/blog/__init__.py
from flask import Blueprint

blog = Blueprint("blog", __name__)

# Import routes AFTER the blueprint exists so the decorators can attach
from app.blueprints.blog import routes  # noqa: E402,F401

# app/blueprints/blog/routes.py
from flask import render_template
from app.blueprints.blog import blog
from app.blueprints.blog.models import Post

@blog.route("/posts")
def list_posts():
    posts = Post.query.order_by(Post.created_at.desc()).all()
    return render_template("blog/posts.html", posts=posts)

Hands-on Exercise

from flask import Flask, render_template
app = Flask(__name__)

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

@app.route("/login")
def login(): return render_template("login.html")

@app.route("/posts")
def posts(): return render_template("posts.html")

# app/blueprints/main.py
from flask import Blueprint, render_template
main = Blueprint("main", __name__)

@main.route("/")
def index():
    return render_template("index.html")

# app/blueprints/auth.py
from flask import Blueprint, render_template
auth = Blueprint("auth", __name__, url_prefix="/auth")

@auth.route("/login")
def login():
    return render_template("login.html")

# app/blueprints/blog.py
from flask import Blueprint, render_template
blog = Blueprint("blog", __name__, url_prefix="/blog")

@blog.route("/posts")
def posts():
    return render_template("posts.html")

# app/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    from app.blueprints.main import main
    from app.blueprints.auth import auth
    from app.blueprints.blog import blog
    app.register_blueprint(main)
    app.register_blueprint(auth)
    app.register_blueprint(blog)
    return app

Best Practices

Summary & Quiz

📚 Further Reading

• Flask Docs — Modular Applications with Blueprints
• Flask Tutorial — Blueprints and Views
• Real Python — Use a Flask Blueprint to Architect Your Applications

🚀 What's Next?

Your factory and blueprints both need settings — database URLs, secret keys, per-environment toggles. Next: Configuration Management, where you'll learn to load config cleanly and keep secrets out of your repo.