Loading Configuration from Files

To keep sensitive credentials like SECRET_KEY and environment-specific settings out of your version control, Flask provides methods to load configuration from external Python scripts, JSON, or TOML files.

Loading from Python Files

To load configuration from a Python file, use the from_pyfile method. This is useful for complex configurations that require logic or for simple key-value pairs.

from flask import Flask

app = Flask(__name__)
app.config.from_pyfile("config.py")

When using from_pyfile, Flask executes the file as Python code. Only variables defined with uppercase names are added to the Config object.

# config.py
DEBUG = True
SECRET_KEY = "dev-key"
database_uri = "sqlite:///tmp.db"  # This will be ignored (lowercase)

Loading from JSON and TOML Files

The from_file method allows you to load configuration from any format, provided you supply a loader function that converts the file content into a mapping (like a dictionary).

JSON Configuration

To load from a JSON file, use the standard json.load function.

import json
from flask import Flask

app = Flask(__name__)
app.config.from_file("config.json", load=json.load)

TOML Configuration

To load from a TOML file, use tomllib.load (available in Python 3.11+). Because tomllib requires the file to be opened in binary mode, you must set text=False.

import tomllib
from flask import Flask

app = Flask(__name__)
app.config.from_file("config.toml", load=tomllib.load, text=False)

As with Python files, only uppercase keys in the JSON or TOML structure will be loaded into the Flask configuration.

Loading from Environment Variables

A common pattern is to point to a configuration file using an environment variable. This allows you to change the configuration file based on the deployment environment without changing the code.

from flask import Flask

app = Flask(__name__)
# Loads the file path from the 'YOURAPP_SETTINGS' environment variable
app.config.from_envvar("YOURAPP_SETTINGS")

Before running the application, set the variable in your terminal:

export YOURAPP_SETTINGS='/path/to/production.cfg'
python app.py

Using the Instance Folder for Secrets

Flask supports an "instance folder" for files that should not be committed to version control, such as configuration files containing secrets. By setting instance_relative_config=True, relative paths passed to config loading methods will be relative to the instance folder instead of the application root.

from flask import Flask

# The instance folder is usually located at /instance next to the app package
app = Flask(__name__, instance_relative_config=True)

# This looks for 'config.py' in the instance folder
app.config.from_pyfile("config.py", silent=True)

Using silent=True ensures that the application does not crash if the configuration file is missing, which is helpful when providing optional overrides.

Troubleshooting

Lowercase Keys are Ignored

Flask's Config class is designed to ignore any keys that are not fully uppercase. If you find that your settings are not being loaded, ensure they are defined in all caps:

# This works
app.config["DATABASE_URL"] = "..."

# This will NOT be loaded by from_pyfile or from_file
app.config["database_url"] = "..."

TOML Loading Errors

If you encounter a TypeError when loading TOML files, ensure you have set text=False in the from_file call. The tomllib.load function expects a binary file stream, while from_file defaults to opening files in text mode.

# Correct for TOML
app.config.from_file("config.toml", load=tomllib.load, text=False)

Relative Paths

By default, relative paths are relative to the application's root_path. If your configuration file is not being found, check if you need to use an absolute path or enable instance_relative_config.