Flask Extension

Dynaconf provides a drop in replacement for app.config.

As Flask encourages the composition by overriding the config_class attribute this extension follows the patterns of Flask and turns your Flask’s app.config in to a dynaconf instance.

Initialize the extension

Initialize the FlaskDynaconf extension in your app

from flask import Flask
from dynaconf import FlaskDynaconf

app = Flask(__name__)
You can optionally use init_app as well.

Use FLASK_ environment variables

Then the app.config will work as a dynaconf.settings instance and FLASK_ will be the global prefix for exporting environment variables.


export FLASK_DEBUG=true              # app.config.DEBUG
export FLASK_INTVALUE=1              # app.config['INTVALUE']
export FLASK_MAIL_SERVER='host.com'  # app.config.get('MAIL_SERVER')

Settings files

You can also have settings files for your Flask app, in the root directory (the same where you execute flask run) put your settings.toml and .secrets.toml files and then define your environments [default], [development] and [production].

To switch the working environment the FLASK_ENV variable can be used, so FLASK_ENV=development to work in development mode or FLASK_ENV=production to switch to production.

IMPORTANT: To use $ dynaconf CLI the FLASK_APP must be defined.

IF you don’t want to manually create your config files take a look at the CLI


It is possible to customize how your Flask project will load settings, example: You want your users to customize a settings file defined in export PROJECTNAME_SETTINGS=/path/to/settings.toml and you want environment variables to be loaded from PROJECTNAME_VARNAME

your flask app.py (or wherever you setup dynaconf)

"""This defines which environment variable global prefix dynaconf will load
That means that `export PROJECTNAME_FOO=1` will be loaded to `app.config.FOO
On command line it is possible to check it with `dynaconf list -k foo`"""

"""This defines which path dynaconf will look to load config files
example: export PROJECTNAME_SETTINGS=/path/to/settings.toml and the format can be
.ini, .json, .yaml or .toml


    export PROJECTNAME_SETTINGS=settings.toml
    FOO = 1
    FOO = 2
    FOO = 3


    export PROJECTNAME_SETTINGS=settings.yaml
      foo: 1
      foo: 2
      foo: 3

It is also possible to pass a list of files::

    export PROJECTNAME_SETTINGS=settings.toml,other_settings.yaml,another.json

The variables will be cascaded in the defined order (last wins the precedence)
The environment variables wins precedence over all!

# load dynaconf
app = Flask(__name__)

Then the working environment can now be switched using export PROJECTNAME_ENV=production

Loading Flask Extensions Dynamically

You can tell Dynaconf to load your Flask Extensions dynamically as long as the extensions follows the Pattens of Flask extensions.

The only requirement is that the extension must be a callable that accepts app as first argument. e.g: flask_admin:Admin or custom_extension.module:init_app and of course the extension must be in Python namespace to be imported.

For extensions initialized just use the class or function path like: “flask_admin:Admin” or “extension.module:init_app”

having a settings.toml


Considering an app.py like:

from flask import Flask
from dynaconf import FlaskDynaconf

app = Flask(__name__)
flask_dynaconf = FlaskDynaconf(app)


Optionally you can pass load_extensions(key="OTHER_NAME") pointing to your list of extensions.

It is also possible to use environment variables to set the extensions to be loaded.

# .env
export FLASK_EXTENSIONS="['flask_admin:Admin']"

The extensions will be loaded in order.

Develoment extensions

It is also possible to have extensions that loads only in development environment.