Skip to content

advanced usage

Programmatically loading a settings file

from dynaconf import settings
settings.load_file(path="/path/to/file.toml")  # list or `;/,` separated allowed

NOTE: programmatically loaded file is not persisted, once env is changed via setenv|ugin_env, or a reload or configure is invoked it will be cleaned, to persist it needs to go to INCLUDES_FOR_DYNACONF variable or you need to load it programmatically again.

Creating new loaders

In your project i.e called myprogram create your custom loader.


def load(obj, env=None, silent=True, key=None, filename=None):
    Reads and loads in to "obj" a single key or all keys from source
    :param obj: the settings instance
    :param env: settings current env (upper case) default='DEVELOPMENT'
    :param silent: if errors should raise
    :param key: if defined load a single key, else load all from `env`
    :param filename: Custom filename to load (useful for tests)
    :return: None
    # Load data from your custom data source (file, database, memory etc)
    # use `obj.set(key, value)` or `obj.update(dict)` to load data
    # use `obj.find_file('filename.ext')` to find the file in search tree
    # Return nothing

In the .env file or exporting the envvar define:

LOADERS_FOR_DYNACONF=['myprogram.my_custom_loader', 'dynaconf.loaders.env_loader']

Dynaconf will import your myprogram.my_custom_loader.load and call it.

IMPORTANT: the 'dynaconf.loaders.env_loader' must be the last in the loaders list if you want to keep the behavior of having envvars to override parameters.

In case you need to disable all external loaders and rely only the settings.* file loaders define:


In case you need to disable all core loaders and rely only on external loaders:

CORE_LOADERS_FOR_DYNACONF='[]'  # a toml empty list

For example, if you want to add a SOPS loader

def load(
    obj: LazySettings,
    env: str = "DEVELOPMENT",
    silent: bool = True,
    key: str = None,
    filename: str = None,
) -> None:
    sops_filename = f"secrets.{env}.yaml"
    sops_file = obj.find_file(sops_filename)
    if not sops_file:
        logger.error(f"{sops_filename} not found! Secrets not loaded!")

    _output = run(["sops", "-d", sops_file], capture_output=True)
    if _output.stderr:
        logger.warning(f"SOPS error: {_output.stderr}")
    decrypted_config = yaml.load(_output.stdout, Loader=yaml.CLoader)

    if key:
        value = decrypted_config.get(key.lower())
        obj.set(key, value)


See more example/custom_loader

Module impersonation

In some cases you may need to impersonate your legacy settings module for example you already have a program that does.

from myprogram import settings

and now you want to use dynaconf without the need to change your whole codebase.

Go to your myprogram/ and apply the module impersonation.

import sys
from dynaconf import LazySettings

sys.modules[__name__] = LazySettings()

the last line of above code will make the module to replace itself with a dynaconf instance in the first time it is imported.

Switching working environments

You can switch between existing environments using:

  • from_env: (recommended) Will create a new settings instance pointing to defined env.
  • setenv: Will set the existing instance to defined env.
  • using_env: Context manager that will have defined env only inside its scope.


New in 2.1.0

Return a new isolated settings object pointing to specified env.

Example of settings.toml::

message = 'This is in dev'
foo = 1
message = 'this is in other env'
bar = 2


>>> from dynaconf import settings
>>> print(settings.MESSAGE)
'This is in dev'
>>> print(settings.FOO)
>>> print(settings.BAR)
AttributeError: settings object has no attribute 'BAR'

Then you can use from_env:

>>> print(settings.from_env('other').MESSAGE)
'This is in other env'
>>> print(settings.from_env('other').BAR)
>>> print(settings.from_env('other').FOO)
AttributeError: settings object has no attribute 'FOO'

The existing settings object remains the same.

>>> print(settings.MESSAGE)
'This is in dev'

You can assign new settings objects to different envs like:

development_settings = settings.from_env('development')
other_settings = settings.from_env('other')

And you can choose if the variables from different envs will be chained and overridden in a sequence:

all_settings = settings.from_env('development', keep=True).from_env('other', keep=True)

>>> print(all_settings.MESSAGE)
'This is in other env'
>>> print(all_settings.FOO)
>>> print(all_settings.BAR)

The variables from [development] are loaded keeping pre-loaded values, then the variables from [other] are loaded keeping pre-loaded from [development] and overriding it.

It is also possible to pass additional configuration variables to from_env method.

new_settings = settings.from_env('production', keep=True, SETTINGS_FILE_FOR_DYNACONF='another_file_path.yaml')

Then the new_settings will inherit all the variables from existing env and also load the another_file_path.yaml production env.


Will change in_place the env for the existing object.

from dynaconf import settings

# now values comes from [other] section of config
assert settings.MESSAGE == 'This is in other env'

# now working env are back to previous


Using context manager

from dynaconf import settings

with settings.using_env('other'):
    # now values comes from [other] section of config
    assert settings.MESSAGE == 'This is in other env'

# existing settings back to normal after the context manager scope
assert settings.MESSAGE == 'This is in dev'

Populating objects

New in 2.0.0

You can use dynaconf values to populate Python objects (instances).


class Obj:

then you can do:

from dynaconf import settings  # assume it has DEBUG=True and VALUE=42.1
obj = Obj()


assert obj.DEBUG is True
assert obj.VALUE == 42.1

Also you can specify only some keys:

from dynaconf import settings  # assume it has DEBUG=True and VALUE=42.1
obj = Obj()

settings.populate_obj(obj, keys=['DEBUG'])

assert obj.DEBUG is True  # ok

assert obj.VALUE == 42.1  # AttributeError


You can generate a file with current configs by calling dynaconf list -o /path/to/file.ext see more in cli

You can also do that programmatically with:

from dynaconf import loaders
from dynaconf import settings
from dynaconf.utils.boxing import DynaBox

# generates a dict with all the keys for `development` env
data = settings.as_dict(env='development')

# writes to a file, the format is inferred by extension
# can be .yaml, .toml, .ini, .json, .py
loaders.write('/path/to/file.yaml', DynaBox(data).to_dict(), merge=False, env='development')

Preloading files

New in 2.2.0

Useful for plugin based apps.

from dynaconf import Dynaconf

settings = Dynaconf(
  preload=["/path/*", "other/settings.toml"],                # <-- Loaded first
  settings_file="/etc/foo/",                      # <-- Loaded second (the main file)
  includes=["other.module.settings", "other/settings.yaml"]  # <-- Loaded at the end


For testing it is recommended to just switch to testing environment and read the same config files.


value = "On Default"

value = "On Testing"

from dynaconf import settings


ENV_FOR_DYNACONF=testing python

Then your will print "On Testing" red from [testing] environment.


For pytest it is common to create fixtures to provide pre-configured settings object or to configure the settings before all the tests are collected.

Examples available on

With pytest fixtures it is recommended to use the FORCE_ENV_FOR_DYNACONF instead of just ENV_FOR_DYNACONF because it has precedence.

A python program

settings.toml with the [testing] environment.

VALUE = "On Default"

VALUE = "On Testing" that reads that value from current environment.

from dynaconf import settings

def return_a_value():
    return settings.VALUE

tests/ with a fixture to force settings to run pointing to [testing] environment.

import pytest
from dynaconf import settings

@pytest.fixture(scope="session", autouse=True)
def set_test_settings():

tests/ to assert that the correct environment is loaded

from app import return_a_value

def test_dynaconf_is_in_testing_env():
    assert return_a_value() == "On Testing"

A Flask program

settings.toml with the [testing] environment.

VALUE = "On Default"

VALUE = "On Testing" that has a Flask application factory

from flask import Flask
from dynaconf.contrib import FlaskDynaconf

def create_app(**config):
    app = Flask(__name__)
    FlaskDynaconf(app, **config)
    return app

tests/ with a fixture to provide app dependency injection to all the tests, And force this app to point to [testing] config environment.

import pytest
from src import create_app

def app():
    app = create_app(FORCE_ENV_FOR_DYNACONF="testing")
    return app

tests/ to assert that the correct environment is loaded

def test_dynaconf_is_on_testing_env(app):
    assert app.config["VALUE"] == "On Testing"
    assert app.config.current_env == "testing"


But it is common in unit tests to mock some objects and you may need in rare cases to mock the dynaconf.settings when running your tests.

from dynaconf.utils import DynaconfDict
mocked_settings = DynaconfDict({'FOO': 'BAR'})

DynaconfDict is a dict like obj that can be populated from a file:

from dynaconf.loaders import toml_loader
toml_loader.load(mocked_settings, filename='my_file.toml', env='testing')