Introducing Flask Unchained

Flask Unchained is a Flask extension, a pluggable application factory, and a set of mostly optional “bundles” that together create a modern, fully integrated, and highly customizable web framework for Flask and its extension ecosystem. Flask Unchained aims to stay true to the spirit and API of Flask, while making it significantly easier to quickly build large web apps and APIs with Flask and SQLAlchemy.

Hello World

Install Flask Unchained

Requires Python 3.6+

pip install "flask-unchained[dev]"

A Basic App

Almost as simple as it gets:

# project-root/
from flask_unchained import AppBundle, Controller, Service, injectable, route
from flask_unchained.pytest import HtmlTestClient

BUNDLES = ['flask_unchained.bundles.controller']

class App(AppBundle):

class HelloService(Service):
    def hello_world(self, name: str) -> str:
        return f'Hello World from {name}!'

class SiteController(Controller):
    hello_service: HelloService = injectable

    def index(self) -> str:
        return self.hello_service.hello_world('Flask Unchained')

class TestSiteController:
    def test_index(self, client: HtmlTestClient):
        r = client.get('site_controller.index')
        assert r.status_code == 200
        assert r.html == 'Hello World from Flask Unchained!'

If you’ve used Flask before, the familiar call to app = Flask(__name__) isn’t missing… That’s a tiny working app right there. Under the easily accessible hood, everything is still just good old Flask. No plumbing, no boilerplate, everything just works!

You can run it like so:

cd project-root
flask run

Included bundles & integrated extensions

Alongside integrating Flask extensions for use by other Flask Unchained apps and bundles, bundles also:

  • utilize simple, consistent, and configurable patterns for writing and sharing Flask code that allows customizing everything from anywhere

  • can be standalone/redistributable Python packages (that share the same patterns for customization, ad infinitum)

  • can be full-blown apps (like say a blog or web store) that your app can integrate, extend, and/or customize

  • each bundle with views is itself a Flask Blueprint (automatically)

New in v0.8: asyncio support [experimental]

Thanks to Quart, Flask Unchained now has preliminary support for building asynchronous web apps with asyncio:

pip install "flask-unchained[dev]" quart
# project-root/
from flask_unchained import AppBundle, Controller, route
from quart import websocket

class App(AppBundle):

class SiteController(Controller):
    async def index(self):
        return await self.render('index')

    @route('/ws', is_websocket=True)
    async def ws(self):
        while True:
            data = await websocket.receive()
            await websocket.send(f'echo {data}')
<!-- project-root/templates/site/index.html -->
<!doctype html>
  <title>Websocket example</title>
  <input type="text" id="message">
  <button type="submit">Send</button>
  <script type="text/javascript">
    var ws = new WebSocket('ws://' + document.domain + ':' + location.port + '/ws');
    ws.onmessage = function (event) {
      var messages_dom = document.getElementsByTagName('ul')[0];
      var message_dom = document.createElement('li');
      var content_dom = document.createTextNode('Received: ' +;

    var button = document.getElementsByTagName('button')[0];
    button.onclick = function () {
      var content = document.getElementsByTagName('input')[0].value;
cd project-root
UNCHAINED_CONFIG="app" flask run

Please note that some included bundles won’t work, because they integrate Flask extensions that don’t work with asyncio. Contributions welcome ;)

Disclaimer: this is alpha/beta quality software

The core is solid, but especially at the edges, there will likely be bugs - and possibly some breaking API changes too. Please file issues on GitHub if you have any questions, encounter any problems, and/or have any feedback!

Thanks and acknowledgements

The architecture of how Flask Unchained and its bundles work is inspired by the Symfony Framework, which is awesome, aside from the fact that it isn’t Python ;)

The Unchained Extension

The “orchestrator” that ties everything together. It handles dependency injection and enables access to much of the public API of flask.Flask and flask.Blueprint:

# project-root/
from flask_unchained import unchained, injectable

def print_hello(name: str, hello_service: HelloService = injectable):

def runs_once_at_startup():
def runs_after_each_request_to_an_app_bundle_view(response):
    return response

The Unchained Extension also plays a role in the app factory:

The App Factory

The app factory discovers all the code from your app and its bundles, and then with it automatically initializes, configures, and “boots up” the Flask app instance for you. I know that sounds like magic, but it’s actually quite easy to understand, and every step it takes can be customized by you if necessary. In barely-pseudo-code, the app factory looks like this:

from flask import Flask
from flask_unchained import DEV, PROD, STAGING, TEST

class AppFactory:
    APP_CLASS = Flask

    def create_app(self, env: Union[DEV, PROD, STAGING, TEST]) -> Flask:
        # load the Unchained Config and configured bundles
        unchained_config = self.load_unchained_config(env)
        app_bundle, bundles = self.load_bundles(unchained_config.BUNDLES)

        # instantiate the Flask app instance
        app = self.APP_CLASS(, **kwargs_from_unchained_config)

        # let bundles configure the app pre-initialization
        for bundle in bundles:

        # discover code from bundles and boot the app using hooks
        unchained.init_app(app, bundles)
            # the Unchained extension runs hooks in their correct order:
            RegisterExtensionsHook.run_hook(app, bundles)
            ConfigureAppHook.run_hook(app, bundles)
            InitExtensionsHook.run_hook(app, bundles)
            RegisterServicesHook.run_hook(app, bundles)
            RegisterCommandsHook.run_hook(app, bundles)
            RegisterRoutesHook.run_hook(app, bundles)
            RegisterBundleBlueprintsHook.run_hook(app, bundles)
            # (there may be more depending on which bundles you enable)

        # let bundles configure the app post-initialization
        for bundle in bundles:

        # return the app instance ready to rock'n'roll
        return app

The flask and pytest CLI commands automatically use the app factory for you, while in production you have to call it yourself:

# project-root/
from flask_unchained import AppFactory, PROD

app = AppFactory().create_app(env=PROD)

For a deeper look check out How Flask Unchained Works.

Going Big (Project Layout)

When you want to expand beyond a single file, Flask Unchained defines a configurable folder structure for you so that everything just works. A common structure might look like this:

├── # the Flask Unchained config
├── app                 # your App Bundle package
│   ├── admins          # Flask-Admin model admins
│   ├── commands        # Click CLI groups/commands
│   ├── extensions      # Flask extensions
│   ├── models          # SQLAlchemy models
│   ├── fixtures        # SQLAlchemy model fixtures (for seeding the dev db)
│   ├── serializers     # Marshmallow serializers (aka schemas)
│   ├── services        # dependency-injectable Services
│   ├── tasks           # Celery tasks
│   ├── templates       # Jinja2 templates
│   ├── views           # Controllers, Resources and ModelResources
│   ├──
│   ├──       # your app config
│   └──       # declarative routes
├── bundles             # custom bundles and/or bundle extensions/overrides
│   └── security        # a customized/extended Security Bundle
│       ├── models
│       ├── serializers
│       ├── services
│       ├── templates
│       └──
├── db
│   └── migrations      # migrations generated by Flask-Migrate
├── static              # the top-level static assets folder
├── templates           # the top-level templates folder
└── tests               # your pytest tests

Want to start building now? Check out the Tutorial! There are also a couple open source example apps available:



Bundles are powerful and flexible. Conceptually, a bundle is a blueprint, and Flask Unchained gives you complete control to configure not only which views from each bundle get registered with your app and at what routes, but also to extend and/or override anything else you might want to from the bundles you enable.

Some examples of what you can customize from bundles include configuration, controllers, resources, and routes, templates, extensions and services, and models and serializers. Each uses simple and consistent patterns that work the same way across every bundle. Extended/customized bundles can themselves also be distributed as their own projects, and support the same patterns for customization, ad infinitum.

Bundle Structure

The example “hello world” app bundle lived in a single file, while a “full” bundle package typically consists of many modules (as shown just above under Project Layout). The module locations for your code are customizable on a per-bundle basis by setting class attributes on your Bundle subclass, for example:

# your_custom_bundle/

from flask_unchained import Bundle

class YourCustomBundle(Bundle):
    config_module_name = 'settings'
    routes_module_name = 'urls'
    views_module_names = ['controllers', 'resources', 'views']

You can see the default module names and the override attribute names to set on your Bundle subclass by printing the ordered list of hooks that will run for your app using flask unchained hooks:

flask unchained hooks

Hook Name             Default Bundle Module  Bundle Module Override Attr
register_extensions   extensions             extensions_module_names
models                models                 models_module_names
configure_app         config                 config_module_name
init_extensions       extensions             extensions_module_names
services              services               services_module_names
commands              commands               commands_module_names
routes                routes                 routes_module_name
bundle_blueprints     (None)                 (None)
blueprints            views                  blueprints_module_names
views                 views                  views_module_names
model_serializers     serializers            model_serializers_module_names
model_resources       views                  model_resources_module_names
celery_tasks          tasks                  celery_tasks_module_names

Bundle Blueprints

Bundles are blueprints, so if you want to define request/response functions that should only run for views from a specific bundle, you can do that like so:

from flask_unchained import Bundle, unchained

class YourCoolBundle(Bundle):
    name = 'your_cool_bundle'  # the default (snake_cased class name)

def this_only_runs_before_requests_to_views_from_your_cool_bundle():

# the other supported decorators are also available:

The API here is the same as flask.Blueprint, however, its methods must be accessed via the Unchained extension. The syntax is @unchained.bundle_name.blueprint_method_name.

Wait but why?

Sadly, there are some very serious technical limitations with the implementation of flask.Blueprint such that its direct usage breaks the power and flexibility of Flask Unchained views. Under the hood, Flask Unchained does indeed use an instance of flask.Blueprint for each bundle - you just never interact with them directly.

You can technically continue using flask.Blueprint strictly for views in your app bundle, however this support is only kept around for porting purposes. Note that even in your app bundle, views from blueprints unfortunately will not work with declarative routing.

Extending and Overriding Bundles

Extending and overriding bundles is pretty simple. All you need to do is subclass the bundle you want to extend in its own Python package, and include that package in your unchained_config.BUNDLES instead of the original bundle. There is no limit to the depth of the bundle hierarchy (other than perhaps your sanity). So, for example, to extend the Security Bundle, it would look like this:

# project-root/bundles/security/

from import SecurityBundle as BaseSecurityBundle

class SecurityBundle(BaseSecurityBundle):
# project-root/

    # ...

The App Bundle

When defining the app bundle, you must subclass AppBundle instead of Bundle:

# project-root/app/

from flask_unchained import AppBundle

class App(AppBundle):

Everything about your app bundle is otherwise the same as for regular bundles, except the app bundle can extend and/or override anything from any bundle.

Controllers and Templates

The controller bundle includes two base classes that all of your views should extend. The first is Controller, which under the hood is actually very similar to flask.views.View, however, they’re not compatible. The second is Resource, which extends Controller, and whose implementation draws much inspiration from Flask-RSETful (specifically, the Resource and Api classes).


Chances are Controller is the base class you want to extend, unless you’re building a RESTful API. Controllers include a bit of magic:

# your_bundle/

from flask_unchained import Controller, route, injectable

 class SiteController(Controller):
     # all of class Meta is optional (automatic defaults shown)
     class Meta:
         abstract: bool = False
         url_prefix = Optional[str] = '/'          # aka no prefix
         endpoint_prefix: str = 'site_controller'  # snake_cased class name
         template_folder: str = 'site'             # snake_cased class name prefix
         template_file_extension: Optional[str] = '.html'
         decorators: List[callable] = ()

     # controllers automatically support dependency injection
     name_service: NameService = injectable

     @route('/foobaz', methods=['GET', 'POST'])
     def foo_baz():
         # template paths can be explicit
         return self.render('site/foo_baz.html')

     def view_one():
         # or just the filename
         return self.render('one')  # equivalent to 'site/one.html'

     def view_two():
         return self.render('two')

     def _protected_function():
         return 'not a view'

On any subclass of Controller that isn’t abstract, all public methods are automatically assigned default routing rules. In the example above, foo_baz has a route decorator, but view_one and view_two do not. The undecorated views will be assigned default routing rules of /view-one and /view-two respectively (the default is to convert the method name to kebab-case). Protected methods (those prefixed with _) are not assigned routes.


Flask Unchained uses the Jinja templating language, just like Flask.

By default bundles are configured to use a templates subfolder. This is customizable per-bundle:

# your_bundle/

from flask_unchained import Bundle

class YourBundle(Bundle):
    template_folder = 'templates'  # the default

Controllers each have their own template folder within Bundle.template_folder. It defaults to the snake_cased class name, with the suffixes Controller or View stripped (if any). You can customize it using Controller.Meta.template_folder.

The default file extension used for templates is configured by setting TEMPLATE_FILE_EXTENSION in your app config. It defaults to .html, and is also configurable on a per-controller basis by setting Controller.Meta.template_file_extension.

Therefore, the above controller corresponds to the following templates folder structure:

├── templates
│   └── site
│       ├── foo_baz.html
│       ├── one.html
│       └── two.html

Extending and Overriding Templates

Templates can be overridden by placing an equivalently named template higher up in the bundle hierarchy (i.e. in a bundle extending another bundle, or in your app bundle).

So for example, the Security Bundle includes default templates for all of its views. They are located at security/login.html, security/register.html, and so on. Thus, to override them, you would make a security folder in your app bundle’s templates folder and put your customized templates with the same names in it. You can even extend the template you’re overriding, using the standard Jinja syntax (this doesn’t work in regular Flask apps):

{# your_app_or_security_bundle/templates/security/login.html #}

{% extends 'security/login.html' %}

{% block content %}
   {{ render_form(login_user_form, endpoint='security_controller.login') }}
{% endblock %}

If you encounter problems, you can set the EXPLAIN_TEMPLATE_LOADING config option to True to help debug what’s going on.

Resources (API Controllers)

The Resource class extends Controller to add support for building RESTful APIs. It adds a bit of magic around specific methods:

Method name on your Resource subclass

HTTP Method

URL Rule



















If you implement any of these methods, then the shown URL rules will automatically be used.

So, for example:

from http import HTTPStatus
from flask_unchained import Resource, injectable, param_converter, request
from import User, UserManager

class UserResource(Resource):
    # class Meta is optional on resources (automatic defaults shown)
    class Meta:
        url_prefix = '/users'
        member_param = '<int:id>'
        unique_member_param = '<int:user_id>'

    # resources are controllers, so they support dependency injection
    user_manager: UserManager = injectable

    def list():
        return self.jsonify(dict(users=self.user_manager.all()))
        # NOTE: returning SQLAlchemy models directly like this is
        # only supported by ModelResource from the API Bundle

    def create():
        data = request.get_json()
        user = self.user_manager.create(**data, commit=True)
        return self.jsonify(dict(user=user), code=HTTPStatus.CREATED)

    def get(user):
        return self.jsonify(dict(user=user)

    def patch(user):
        data = request.get_json()
        user = self.user_manager.update(user, **data, commit=True)
        return self.jsonify(dict(user=user))

    def put(user):
        data = request.get_json()
        user = self.user_manager.update(user, **data, commit=True)
        return self.jsonify(dict(user=user))

    def delete(user):
        self.user_manager.delete(user, commit=True)
        return self.make_response('', code=HTTPStatus.NO_CONTENT)

Registered like so:

routes = lambda: [

Results in the following routes:

GET     /users             UserResource.list
POST    /users             UserResource.create
GET     /users/<int:id>    UserResource.get
PATCH   /users/<int:id>    UserResource.patch
PUT     /users/<int:id>    UserResource.put
DELETE  /users/<int:id>    UserResource.delete

Declarative Routing

Using declarative routing, your app bundle has final say over which views (from all bundles) should get registered with the app, as well as their routing rules. By default, it uses the rules decorated on views:

# project-root/app/

from flask_unchained import (controller, resource, func, include, prefix,
                             delete, get, patch, post, put, rule)

from import SecurityController

from .views import SiteController

routes = lambda: [

By running flask urls, we can verify it does what we want:

flask urls
Method(s)  Rule                     Endpoint                    View
      GET  /static/<path:filename>  static                      flask.helpers.send_static_file
      GET  /                        site_controller.index       app.views.SiteController.index
      GET  /hello                   site_controller.hello       app.views.SiteController.hello
GET, POST  /login                   security_controller.login
      GET  /logout                  security_controller.logout

Declarative routing can also be much more powerful when you want it to be. For example, to build a RESTful SPA with the Security Bundle, your routes might look like this:

# project-root/app/

from flask_unchained import (controller, resource, func, include, prefix,
                             delete, get, patch, post, put, rule)

from import SecurityController, UserResource

from .views import SiteController

routes = lambda: [

    controller('/auth', SecurityController, rules=[
        get('/reset-password/<token>', SecurityController.reset_password,
    prefix('/api/v1', [
        controller('/auth', SecurityController, rules=[
            get('/check-auth-token', SecurityController.check_auth_token,
                endpoint='security_api.check_auth_token', only_if=True),
            post('/login', SecurityController.login,
            get('/logout', SecurityController.logout,
            post('/forgot-password', SecurityController.forgot_password,
            post('/reset-password/<token>', SecurityController.reset_password,
            post('/change-password', SecurityController.change_password,
        resource('/users', UserResource),

Which results in the following:

flask urls
Method(s)  Rule                                  Endpoint                              View
      GET  /static/<path:filename>               static                                flask.helpers.send_static_file
      GET  /                                     site_controller.index                 app.views.SiteController.index
      GET  /hello                                site_controller.hello                 app.views.SiteController.hello
      GET  /auth/reset-password/<token>          security_api.reset_password 
      GET  /api/v1/auth/check-auth-token         security_api.check_auth_token
     POST  /api/v1/auth/login                    security_api.login          
      GET  /api/v1/auth/logout                   security_api.logout         
     POST  /api/v1/auth/send-confirmation-email  security_api.send_confirmation_email
     POST  /api/v1/auth/forgot-password          security_api.forgot_password
     POST  /api/v1/auth/reset-password/<token>   security_api.post_reset_password
     POST  /api/v1/auth/change-password          security_api.change_password
     POST  /api/v1/users                         user_resource.create        
      GET  /api/v1/users/<int:id>                user_resource.get           
    PATCH  /api/v1/users/<int:id>                user_resource.patch         

Here is a summary of the functions imported at the top of the module:

Declarative Routing Functions




Include all of the routes from the specified module at that point in the tree.


Prefixes all of the child routing rules with the given prefix.


Registers a function-based view with the app, optionally specifying the routing rules.


Registers a controller and its views with the app, optionally customizing the routes to register.


Registers a resource and its views with the app, optionally customizing the routes to register.


Define customizations to a controller/resource method’s route rules.

get(), patch(), post(), put(), and delete()

Like rule() except specifically for each HTTP method.

Dependency Injection

Flask Unchained supports dependency injection of services and extensions (by default).


For services to be automatically discovered, they must subclass Service and (by default) live in a bundle’s services or managers modules. You can however manually register anything as a “service”, even plain values if you really wanted to, using the unchained.service decorator and/or the unchained.register_service method:

from flask_unchained import unchained

class SomethingNotExtendingService:

A_CONST = 'a constant'
unchained.register_service('A_CONST', A_CONST)

Services can request other services be injected into them, and as long as there are no circular dependencies, it will work:

from flask_unchained import Service, injectable

class OneService(Service):
    something: SomethingNotExtendingService = injectable
    A_CONST: str = injectable

class TwoService(Service):
    one_service: OneService = injectable

By setting the default value of a class attribute or function/method argument to the flask_unchained.injectable constant, you are informing the Unchained extension that it should inject those arguments.


The names of services must be unique across all of the bundles in your app (by default services are named as the snake_cased class name). If there are any conflicting class names then you will need to use the unchained.service decorator or the unchained.register_service method to customize the name the service gets registered under:

from flask_unchained import Service, unchained

class ServiceWithNameConflict(Service):

Automatic Dependency Injection

Dependency injection works automatically on all classes extending Service and Controller. The easiest way is with class attributes:

from flask_unchained import Controller, injectable
from import Security, SecurityService
from flask_unchained.bundles.sqlalchemy import SessionManager

class SecurityController(Controller):
    security: Security = injectable
    security_service: SecurityService = injectable
    session_manager: SessionManager = injectable

It also works on the constructor, which is functionally equivalent, just more verbose:

class SiteController(Controller):
    def __init__(self, security: Security = injectable): = security

Manual Dependency Injection

You can use the unchained.inject decorator just about anywhere else you want to inject something:

from flask_unchained import unchained, injectable

# decorate a class to use class attributes injection
class Foobar:
    some_service: SomeService = injectable

    # or you can decorate individual methods
    def a_method(self, another_service: AnotherService = injectable):

# it works on regular functions too
def a_function(some_service: SomeService = injectable):

Alternatively, you can also use unchained.get_local_proxy:

from flask_unchained import unchained

db = unchained.get_local_proxy('db')

Extending and Overriding Services

Services are just classes, so they follow the normal Python inheritance rules. All you need to do is name your service the same as the one you want to customize, placed in the services module higher up in the bundle hierarchy (i.e. in a bundle extending another bundle, or in your app bundle).

Integrating Flask Extensions

Extensions that can be used in Flask Unchained bundles have a few limitations. The primary one being, the extension must implement init_app, and its signature must take a single argument: app. Some extensions fit this restriction out of the box, but often times you will need to subclass the extension to make sure its init_app signature matches. You can create new config options to replace arguments that were originally passed into the extension’s constructor and/or init_app method.

In order for Flask Unchained to actually discover and initialize the extension you want to include, they must be placed in your bundle’s extensions module. It looks like this:

# your_bundle/

from flask_whatever import WhateverExtension

whatever = WhateverExtension()

    'whatever': whatever,

The keys of the EXTENSIONS dictionary serve as the name that will be used to reference the extension at runtime (and for dependency injection). There can be multiple extensions per bundle, and you can also declare other extensions as dependencies that must be initialized before yours:

    'whatever': (whatever, ['dep_ext_one', 'dep_ext_two']),