Registering Blueprints

A blueprint only becomes active after you register it.

diagram a blueprint is a set of routes waiting for an application mermaid

  flowchart TD
  A["bp = Blueprint('admin', __name__, url_prefix='/admin')"] --> B["@bp.route('/users')"]
  B --> C["nothing is reachable yet -- there is no app"]
  C --> D["app.register_blueprint(bp)"]
  D --> E["rule becomes /admin/users"]
  D --> F["endpoint becomes 'admin.users'"]
  E --> G["url_for('admin.users') -> /admin/users"]
  F --> G
  H["app.route('/users') separately"] --> I["url_for('users') -> /users"]
  G -.->|"no collision -- different endpoint names"| I

Defining a blueprint registers nothing. The routes exist on the blueprint object, and only when the app registers it do they get a URL prefix and a namespaced endpoint. That is what lets the same blueprint be mounted at a different prefix, or in a different app, without editing it.

The endpoint name is namespaced, which is the point

Verified with an app-level /users view and an admin blueprint that also defines /users:

Request	Serves
GET /users	the app-level view
GET /admin/users	the blueprint view

and for building URLs:

python

url_for("users")        # /users
url_for("admin.users")  # /admin/users

Two views may share a function name because the endpoint is blueprint.function. Forgetting the prefix inside a blueprint template is the usual cause of BuildError: Could not build url for endpoint 'users' — within a blueprint you can also write url_for(".users"), where the leading dot means “this blueprint”.

Registering the same blueprint object twice on one app raises:

text

ValueError: The name 'admin' is already registered for this blueprint.

Mounting it twice on purpose is possible, but you must pass a distinct name=.

Basic registration

python

from flask import Flask
from auth.routes import auth_bp
 
app = Flask(__name__)
app.register_blueprint(auth_bp)

url_prefix

url_prefix groups routes under a prefix.

python

app.register_blueprint(auth_bp, url_prefix="/auth")

If a blueprint defines /login, it becomes:

• /auth/login

Endpoint naming

Endpoints become namespaced by blueprint name:

• auth.login

So in templates you’ll often do:

python

url_for("auth.login")

This avoids collisions when multiple blueprints have the same function name.

Where do templates live?

Blueprints can have their own templates folder, but many projects keep templates in one place.

Both approaches work; pick a convention and stay consistent.