Configuration Handling

Applications need some kind of configuration. There are different settingsyou might want to change depending on the application environment liketoggling the debug mode, setting the secret key, and other suchenvironment-specific things.

The way Flask is designed usually requires the configuration to beavailable when the application starts up. You can hard code theconfiguration in the code, which for many small applications is notactually that bad, but there are better ways.

Independent of how you load your config, there is a config objectavailable which holds the loaded configuration values:The config attribute of the Flaskobject. This is the place where Flask itself puts certain configurationvalues and also where extensions can put their configuration values. Butthis is also where you can have your own configuration.

Configuration Basics

The config is actually a subclass of a dictionary andcan be modified just like any dictionary:

app = Flask(__name__)
app.config['TESTING'] = True

Certain configuration values are also forwarded to theFlask object so you can read and write them from there:

app.testing = True

To update multiple keys at once you can use the dict.update()method:

app.config.update(
    TESTING=True,
    SECRET_KEY=b'_5#y2L"F4Q8z\n\xec]/'
)

Environment and Debug Features

The ENV and DEBUG config values are special because theymay behave inconsistently if changed after the app has begun setting up.In order to set the environment and debug mode reliably, Flask usesenvironment variables.

The environment is used to indicate to Flask, extensions, and otherprograms, like Sentry, what context Flask is running in. It iscontrolled with the FLASK_ENV environment variable anddefaults to production.

Setting FLASK_ENV to development will enable debug mode.flask run will use the interactive debugger and reloader by defaultin debug mode. To control this separately from the environment, use theFLASK_DEBUG flag.

$ export FLASK_ENV=development$ flask run

$ python -c 'import os; print(os.urandom(16))'b'_5#y2L"F4Q8z\n\xec]/'

127.0.0.1 localhost.dev

Configuring from Files

Configuration becomes more useful if you can store it in a separate file,ideally located outside the actual application package. This makespackaging and distributing your application possible via various packagehandling tools (Deploying with Setuptools) and finally modifying theconfiguration file afterwards.

So a common pattern is this:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

This first loads the configuration from theyourapplication.default_settings module and then overrides the valueswith the contents of the file the YOURAPPLICATION_SETTINGSenvironment variable points to. This environment variable can be set onLinux or OS X with the export command in the shell before starting theserver:

$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ python run-app.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader...

On Windows systems use the set builtin instead:

> set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg

The configuration files themselves are actual Python files. Only valuesin uppercase are actually stored in the config object later on. So makesure to use uppercase letters for your config keys.

Here is an example of a configuration file:

# Example configuration
DEBUG = False
SECRET_KEY = b'_5#y2L"F4Q8z\n\xec]/'

Make sure to load the configuration very early on, so that extensions havethe ability to access the configuration when starting up. There are othermethods on the config object as well to load from individual files. For acomplete reference, read the Config object’sdocumentation.

Configuring from Environment Variables

In addition to pointing to configuration files using environment variables, youmay find it useful (or necessary) to control your configuration values directlyfrom the environment.

Environment variables can be set on Linux or OS X with the export command inthe shell before starting the server:

$ export SECRET_KEY='5f352379324c22463451387a0aec5d2f'
$ export MAIL_ENABLED=false
$ python run-app.py
 * Running on http://127.0.0.1:5000/

On Windows systems use the set builtin instead:

> set SECRET_KEY='5f352379324c22463451387a0aec5d2f'

While this approach is straightforward to use, it is important to remember thatenvironment variables are strings – they are not automatically deserializedinto Python types.

Here is an example of a configuration file that uses environment variables:

import os
 
_mail_enabled = os.environ.get("MAIL_ENABLED", default="true")
MAIL_ENABLED = _mail_enabled.lower() in {"1", "t", "true"}
 
SECRET_KEY = os.environ.get("SECRET_KEY")
 
if not SECRET_KEY:
    raise ValueError("No SECRET_KEY set for Flask application")

Notice that any value besides an empty string will be interpreted as a booleanTrue value in Python, which requires care if an environment explicitly setsvalues intended to be False.

Make sure to load the configuration very early on, so that extensions have theability to access the configuration when starting up. There are other methodson the config object as well to load from individual files. For a completereference, read the Config class documentation.

Configuration Best Practices

The downside with the approach mentioned earlier is that it makes testinga little harder. There is no single 100% solution for this problem ingeneral, but there are a couple of things you can keep in mind to improvethat experience:

• Create your application in a function and register blueprints on it.That way you can create multiple instances of your application withdifferent configurations attached which makes unit testing a loteasier. You can use this to pass in configuration as needed.

• Do not write code that needs the configuration at import time. If youlimit yourself to request-only accesses to the configuration you canreconfigure the object later on as needed.

Development / Production

Most applications need more than one configuration. There should be atleast separate configurations for the production server and the one usedduring development. The easiest way to handle this is to use a defaultconfiguration that is always loaded and part of the version control, and aseparate configuration that overrides the values as necessary as mentionedin the example above:

app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')

Then you just have to add a separate config.py file and exportYOURAPPLICATION_SETTINGS=/path/to/config.py and you are done. Howeverthere are alternative ways as well. For example you could use imports orsubclassing.

What is very popular in the Django world is to make the import explicit inthe config file by adding from yourapplication.defaultsettingsimport * to the top of the file and then overriding the changes by hand.You could also inspect an environment variable likeYOURAPPLICATION_MODE and set that to _production, development etcand import different hard-coded files based on that.

An interesting pattern is also to use classes and inheritance forconfiguration:

class Config(object):
    DEBUG = False
    TESTING = False
    DATABASE_URI = 'sqlite:///:memory:'
 
class ProductionConfig(Config):
    DATABASE_URI = 'mysql://[email protected]/foo'
 
class DevelopmentConfig(Config):
    DEBUG = True
 
class TestingConfig(Config):
    TESTING = True

To enable such a config you just have to call intofrom_object():

app.config.from_object('configmodule.ProductionConfig')

Note that from_object() does not instantiate the classobject. If you need to instantiate the class, such as to access a property,then you must do so before calling from_object():

from configmodule import ProductionConfig
app.config.from_object(ProductionConfig())
 
# Alternatively, import via string:
from werkzeug.utils import import_string
cfg = import_string('configmodule.ProductionConfig')()
app.config.from_object(cfg)

Instantiating the configuration object allows you to use @property inyour configuration classes:

class Config(object):
    """Base config, uses staging database server."""
    DEBUG = False
    TESTING = False
    DB_SERVER = '192.168.1.56'
 
    @property
    def DATABASE_URI(self):         # Note: all caps
        return 'mysql://[email protected]{}/foo'.format(self.DB_SERVER)
 
class ProductionConfig(Config):
    """Uses production database server."""
    DB_SERVER = '192.168.19.32'
 
class DevelopmentConfig(Config):
    DB_SERVER = 'localhost'
    DEBUG = True
 
class TestingConfig(Config):
    DB_SERVER = 'localhost'
    DEBUG = True
    DATABASE_URI = 'sqlite:///:memory:'

There are many different ways and it’s up to you how you want to manageyour configuration files. However here a list of good recommendations:

• Keep a default configuration in version control. Either populate theconfig with this default configuration or import it in your ownconfiguration files before overriding values.

• Use an environment variable to switch between the configurations.This can be done from outside the Python interpreter and makesdevelopment and deployment much easier because you can quickly andeasily switch between different configs without having to touch thecode at all. If you are working often on different projects you caneven create your own script for sourcing that activates a virtualenvand exports the development configuration for you.

• Use a tool like fabric in production to push code andconfigurations separately to the production server(s). For somedetails about how to do that, head over to theDeploying with Fabric pattern.

Instance Folders

With Flask 0.8 a new attribute was introduced:Flask.instance_path. It refers to a new concept called the“instance folder”. The instance folder is designed to not be underversion control and be deployment specific. It’s the perfect place todrop things that either change at runtime or configuration files.

You can either explicitly provide the path of the instance folder whencreating the Flask application or you can let Flask autodetect theinstance folder. For explicit configuration use the _instance_path_parameter:

app = Flask(__name__, instance_path='/path/to/instance/folder')

Please keep in mind that this path must be absolute when provided.

If the instance_path parameter is not provided the following defaultlocations are used:

• Uninstalled module:

/myapp.py
/instance

• Uninstalled package:

/myapp
    /__init__.py
/instance

• Installed module or package:

$PREFIX/lib/python2.X/site-packages/myapp
$PREFIX/var/myapp-instance

$PREFIX is the prefix of your Python installation. This can be/usr or the path to your virtualenv. You can print the value ofsys.prefix to see what the prefix is set to.

Since the config object provided loading of configuration files fromrelative filenames we made it possible to change the loading via filenamesto be relative to the instance path if wanted. The behavior of relativepaths in config files can be flipped between “relative to the applicationroot” (the default) to “relative to instance folder” via theinstance_relative_config switch to the application constructor:

app = Flask(__name__, instance_relative_config=True)

Here is a full example of how to configure Flask to preload the configfrom a module and then override the config from a file in the instancefolder if it exists:

app = Flask(__name__, instance_relative_config=True)
app.config.from_object('yourapplication.default_settings')
app.config.from_pyfile('application.cfg', silent=True)

The path to the instance folder can be found via theFlask.instance_path. Flask also provides a shortcut to open afile from the instance folder with Flask.open_instance_resource().

Example usage for both:

filename = os.path.join(app.instance_path, 'application.cfg')
with open(filename) as f:
    config = f.read()
 
# or via open_instance_resource:
with app.open_instance_resource('application.cfg') as f:
    config = f.read()