Settings Files¶
Optionally you can store settings in files, dynaconf supports multiple file formats, you are recommended to choose one format but you can also use mixed settings formats across your application.
Tip
You are not required to use settings files, if not specified dynaconf can load your data only from environment variables
Supported formats¶
- .toml - Default and recommended file format.
- .yaml|.yml - Recommended for Django applications. (see yaml caveats)
- .json - Useful to reuse existing or exported settings.
- .ini - Useful to reuse legacy settings.
- .py - Not Recommended but supported for backwards compatibility.
- .env - Useful to automate the loading of environment variables.
Info
Create your settings in desired format and specify it on settings_files
argument on your dynaconf instance or pass it in -f <format>
if using dynaconf init
command.
Tip
Can't find the file format you need for your settings? You can create your custom loader and read any data source. read more on extending dynaconf
Warning
To use the .ini
or .properties
file format you need to install extra dependency
pip install configobj
or pip install dynaconf[ini]
Reading settings from files¶
On files by default dynaconf loads all the existing keys and sections as first level settings.
name = "Bruno"
name: Bruno
{"name": "Bruno"}
name = 'Bruno'
NAME = "Bruno"
⚠️ on
.py
files dynaconf only read UPPERCASE variables.
Then on your application code:
settings.name == "Bruno"
Info
The default encoding when loading the settings files is utf-8
and it can be customized
via encoding
parameter.
Settings file location¶
Dynaconf will search files specified in settings_file
option starting the search tree
on the current working dir (the directory where your program is located).
Ex:
from dynaconf import Dynaconf
settings = Dynaconf(settings_files=["settings.toml", "/etc/program/foo.yaml"])
Info
To use python -m module
, where the module uses dynaconf you will need to
specify your settings.toml
path, for example, like this: settings_file="module/config/settings.toml"
.
settings.toml¶
In the above example, dynaconf will try to load settings.toml
from the same
directory where the program is located, also known as .
and then will
keep traversing the folders in backwards order until the root is located.
root is either the path where the program was invoked, or the O.S root or the root
specified in root_path
.
/etc/program/foo.yaml¶
Dynaconf will then recognize this as an absolute path and will try to load it directly from the specified location.
Local Settings files¶
For each file specified in settings_files
dynaconf will also try to load
an optional name
.local.extension
.
For example, settings_files=["settings.toml"]
will make dynaconf to search for settings.toml
and then also search for settings.local.toml
Includes¶
You can also specify includes so dynaconf can include those settings after the normal loading.
as a parameter¶
settings = Dynaconf(includes=["path/to/file.toml", "or/a/glob/*.yaml])
as a variable in a file¶
dynaconf_include = ["path/to/file.toml"]
key = value
anotherkey = value
Note
The paths passed to includes are relative to the root_path
of Dynaconf instance or if that is not set, relative
to the directory where the first loaded file is located, includes also accepts globs and absolute paths.
Layered environments on files¶
It is also possible to make dynaconf to read the files separated by layered environments so each section or first level key is loaded as a distinct environment.
settings = Dynaconf(environments=True)
[default]
name = ""
[development]
name = "developer"
[production]
name = "admin"
default:
name: ''
development:
name: developer
production:
name: admin
{
"default": {
"name": ""
},
"development": {
"name": "developer"
},
"production": {
"name": "admin"
}
}
[default]
name = ""
[development]
name = "developer"
[production]
name = "admin"
ℹ️ You can define custom environment using the name you want
[default]
and[global]
are the only environments that are special. You can for example name it[testing]
or[anything]
Then in your program you can use environment variables to switch environments.
export ENV_FOR_DYNACONF=development
settings.name == "developer"
export ENV_FOR_DYNACONF=production
settings.name == "admin"
Warning
On Flask and Django extensions the default behaviour is already
the layered environments.
Also to switch the environment you use export FLASK_ENV=production
or export DJANGO_ENV=production
respectively.
Tip
It is also possible to switch environments programmatically passing
env="development"
to Dynaconf
class on instantiation.
YAML Caveats¶
Nonetypes¶
Yaml parser used by dynaconf (ruamel.yaml) reads undefined values as None
so
key:
key: ~
key: null
All those 3 keys will be parsed as python's None
object.
When using a validator to set a default value for those values you might want to use one of:
Validator("key", default="thing", apply_default_on_none=True)
This way dynaconf will consider the default value even if setting is None
on yaml.
or on yaml you can set the value to @empty
key: "@empty"
NEW in 3.1.9