Configuration
When create your instance of Dynaconf
settings object
there are some customizable parameters.
On instance options¶
Configurations can be passed explicitly to your instance.
from dynaconf import Dynaconf
settings = Dynaconf(
envvar_prefix="MYPROGRAM",
settings_files=["settings.toml", ".secrets.toml"],
environments=True,
load_dotenv=True,
env_switcher="MYPROGRAM_ENV",
**more_options
)
on environment options¶
And can also be exported as environment variables following the rule of being all UPPERCASE
and suffixed with _FOR_DYNACONF
.
export ENVVAR_PREFIX_FOR_DYNACONF=MYPROGRAM
export SETTINGS_FILES_FOR_DYNACONF="['settings.toml', ...]"
export ENVIRONMENTS_FOR_DYNACONF=true
export LOAD_DOTENV_FOR_DYNACONF=true
export ENV_SWITCHER_FOR_DYNACONF=MYPROGRAM_ENV
Available options¶
Info
When exporting as env vars ensure to use UPPERCASE and add the _FOR_DYNACONF
suffix. example: export AUTO_CAST_FOR_DYNACONF=true
Tip
Env vars are cast using the TOML parser, so =FOO
is str
, =42
is int
, =42.1
is float
, =[1, 2]
is a list
and ={foo="bar"}
is a dict
and finally =true
is a boolean. (to force a string value enclose it in quotes: ="'42'"
is str, '42'
)
auto_cast¶
Auto cast is the ability of using special tokens to cast settings variables.
ex: @format {env[HOME]}
, @int 32
, @json {...}
- type: bool
- default: true
commentjson_enabled¶
Enables comments in JSON settings files, but commentjson
must be installed, i.e.: pip install commentjson
- type: bool
- default: false
core_loaders¶
The list of enabled loaders that dynaconf will use to load settings files, if your application is using only YAML
you can for example change it to ['YAML']
so dynaconf stops trying to load toml
and other formats.
- type: list
- default:
[‘YAML’, ‘TOML’, ‘INI’, ‘JSON’, ‘PY’]
default_env¶
When environments
is set, dynaconf will use this value as the environment holding the default values,
ex: in a toml
file it will be [default]
section.
- type: str
- default: "default"
dotenv_override¶
When load_dotenv
is enabled, this controls if variables in .env
will override the values exported as env vars.
- type: boolean
- default: false
dotenv_path¶
Sets the location of the .env
file to either the full path or the containing directory.
- type: str
- default: "." (or the same as project_root)
dotenv_verbose¶
Controls the verbosity of dotenv loader.
- type: boolean
- default: false
encoding¶
Which encoding to use when loading settings files.
- type: str
- default: "utf-8"
environments¶
Controls if dynaconf will work in a multi-layered environment system allowing [default]
, [development]
, [production]
and other environment separations.
- type: boolean or a list
- default: false
envvar¶
This variable changes the location of the settings file that loads the environment variables,
ex: export SETTINGS_FILE_FOR_DYNACONF=another/path/settings.toml
- type: str
- default: "SETTINGS_FILE_FOR_DYNACONF"
envvar_prefix¶
The prefix used by dynaconf to load values from environment variables. You might want your users
to export values using your app name, ex: export MYPROGRAM_DEBUG=true
- type: str
- default: "DYNACONF"
env¶
When environments
is set, this controls the current environment used in runtime.
This is usually set using an environment variable.
export ENV_FOR_DYNACONF=production
Or per execution: ENV_FOR_DYNACONF=production program.py
- type: str
- default: "development"
env_switcher¶
By default ENV_FOR_DYNACONF
is the variable used to switch envs, but you can set this to another variable name.
ex: MYPROGRAM_ENV=production
- type: str
- default: "ENV_FOR_DYNACONF"
force_env¶
When environments
is enabled it might be useful to force an specific env for testing purposes.
- type: str
- default: None
fresh_vars¶
In some cases you might need some variables to be always reloaded from source without the need to reload the application. Variables passed in this list when accessed will always trigger a reload from source, settings files will be read, envvars parsed and external loaders connected.
- type: list
- default: []
ex: fresh_vars=["password"]
so when accessing settings.password
it will be read from source not cache.
includes¶
After loading the files specified in settings_files
dynaconf will load all the files added to includes
in a post-load process.
- type: list
- default: []
Tip
Includes can also be added inside files itself, ex:
includes: ['otherfile.toml']
key: "value"
export INCLUDES_FOR_DYNACONF="['otherfile.toml', 'path/*.yaml']"
Warning
includes are loaded relative to the first loaded file, so if you have a settings_files=['conf/settings.toml']
and includes=["*.yaml"]
the yaml files will be loaded relative to the conf
folder. Unless you specify the absolute path or pass root_path
to the Dynaconf
initializer.
loaders¶
The list of loaders dynaconf will trigger after its core loaders, this list is useful to include custom loaders and also to control the loading of env vars as the last step.
Warning
By default the env_loader
will be latest on this list, so it ensures environment variables has
the priority following the Unix philosophy.
- type: list
- default: ['dynaconf.loaders.env_loader']
Learn more about loaders
load_dotenv¶
When turned on, dynaconf will try to load the variables from a .env
file.
- type: bool
- default: false
lowercase_read¶
By default dynaconf allows the access of first level vars as lowercase, so settings.foo
and settings.FOO
are equivalent (case insensitive). IF needed it can be disabled.
- type: bool
- default: true
merge_enabled¶
If the specified Dynaconf enters in a GLOBAL MERGE mode and when loading new files or sources will not override but merge data structures by default.
- type: bool
- default: false
ex:
# settings.toml
[server]
data = {port=8888}
# other.toml
[server]
data = {address='server.com'}
With merge_enabled
the ending settings.server
will be
{"port": 8888, "address": "server.com"}
nested_separator¶
One of the merging strategies is the use of __
to access nested level data structures. By default the separator is __
(double underline), this variable allows you to change that.
Warning
Choose something that is suitable for env vars, usually you don't need to change this variable.
- type: str
- default: "__"
ex:
export DYNACONF_DATABASES__default__ENGINE__Address="0.0.0.0"
generates:
DATABASES = {
"default": {
"ENGINE": {
"Address": "0.0.0.0"
}
}
}
Warning
On windows env vars are all transformed to upper case.
preload¶
Sometimes you might need to load some file before dynaconf starts looking for its settings_files
or includes
, you can have for example a dynaconf.toml
to hold dynaconf's configuration.
- type: list
- default: []
redis_enabled¶
If set to true
dynaconf will include dynaconf.loaders.redis_loaders
in the loaders
list.
- type: bool
- default: false
redis¶
When redis_enabled
is true, a dictionary holding redis settings.
- type: dict
- default:
{ "host": "REDIS_HOST_FOR_DYNACONF" or "localhost", "port": int("REDIS_PORT_FOR_DYNACONF" or 6379), "db": int("REDIS_DB_FOR_DYNACONF" or 0), "decode_responses": "REDIS_DECODE_FOR_DYNACONF" or True, }
root_path¶
The working path for dynaconf to use as starting point when searching for files:
- type: str
- default: None
Read more on settings_files
secrets¶
This variable is useful for CI and Jenkins, usually set as environment variable pointing to a file containing the secrets to be loaded.
- type: str
- default: None
ex: export SECRETS_FOR_DYNACONF=path/to/secrets.yaml
settings_file or settings_files¶
Info
This variable is required.
The path for the files you wish dynaconf to load the settings from.
It can be settings_file
(singular) or settings_files
(multiple).
- type: str or list
- default: []
Starting on v3.0.0 dynaconf will load only files specified on this variables.
Must be a list
:
settings_files=["file1.toml", "file2.toml"]
or a str
separated by semicolons or commas.
settings_files="file1.toml;file2.toml"
settings_files="file1.toml,file2.toml"
Also it can be a single file.
settings_file="settings.toml"
Or specified as env var.
# singular
export SETTINGS_FILE_FOR_DYNACONF="/etc/program/settings.toml"
# multiple
export SETTINGS_FILES_FOR_DYNACONF="/etc/program/settings.toml;/tmp/foo.yaml"
Read more on settings_files
filtering_strategy¶
Callable accepting data to be filtered, inbuilts currently include PrefixFilter
- type: class
- default: None
skip_files¶
When using a glob on includes
you might want dynaconf to ignore some files that matches.
- type: list
- default: None
skip_files=["path/to/ignored.toml"]
validators¶
A list of validators to be triggered right after the Dynaconf
initialization.
- type: list
- default: []
validators=[
Validator("FOO", must_exist=True)
]
vault_enabled¶
If set to true
dynaconf will include dynaconf.loaders.vault_loader
in the loaders
list.
- type: bool
- default: false
vault¶
When vault_enabled
is true, a dictionary holding vault settings.
- type: dict
-
default:
Read more on Secrets{ "url": "VAULT_URL_FOR_DYNACONF" or f"{vault_scheme}://{vault_host}:{vault_port}", "token": "VAULT_TOKEN_FOR_DYNACONF" or None, "cert": "VAULT_CERT_FOR_DYNACONF" or None, "verify": "VAULT_VERIFY_FOR_DYNACONF" or None, "timeout": "VAULT_TIMEOUT_FOR_DYNACONF" or None, "proxies": "VAULT_PROXIES_FOR_DYNACONF" or None, "allow_redirects": "VAULT_ALLOW_REDIRECTS_FOR_DYNACONF" or None, }
yaml_loader¶
The loader to use for YAML.
- type: str
- default: full_load
Options: safe_load, unsafe_load, full_load
dotted_lookup¶
By default dynaconf reads .
as separator when setting and reading values.
this feature can be disabled by setting dotted_lookup=False
- type: bool
- default: True
Tip
This can also be set per file using dynaconf_dotted_lookup: false
in the top level of the file and works for setting values. For reading you can pass setting.get("key.other", dotted_lookup=False)
Options: True, False
apply_default_on_none¶
YAML reads empty values as None
in this case if you want to have Validator
defaults applied
to the None
values you must set apply_default_on_none
on Dynaconf
class or specific on Validator
instance.