DEV Community

Bruno Rocha
Bruno Rocha

Posted on

from dynaconf import settings

Often when starting a new Python project we need to spend some time thinking about how to manage the settings, decide on which module the configuration manager will be written, decide which name to give to this module, create a class or function to store the configuration keys, create the conditions for multiple environments and still need to worry about where these keys will be stored and in which file format?

No more! now you have Dynaconf!

GitHub logo dynaconf / dynaconf

Configuration Management for Python ⚙

dynaconf. new logo

dynaconf - Configuration Management for Python.

MIT License PyPI PyPI PyPI - Downloads CI codecov Codacy Badge GitHub stars GitHub Release Date GitHub commits since latest release GitHub last commit Code Style Black

GitHub issues User Forum Join the chat at  Matrix


  • Inspired by the 12-factor application guide
  • Settings management (default values, validation, parsing, templating)
  • Protection of sensitive information (passwords/tokens)
  • Multiple file formats toml|yaml|json|ini|py and also customizable loaders.
  • Full support for environment variables to override existing settings (dotenv support included).
  • Optional layered system for multi environments [default, development, testing, production]
  • Built-in support for Hashicorp Vault and Redis as settings and secrets storage.
  • Built-in extensions for Django and Flask web frameworks.
  • CLI for common operations such as init, list, write, validate, export.
  • full docs on


$ pip install dynaconf
Enter fullscreen mode Exit fullscreen mode

Initialize Dynaconf on project root directory

$ cd path/to/your/project/
$ dynaconf init -f toml

⚙️  Configuring your Dynaconf environment
🐍 The file `` was generated.

🎛️  settings.toml created to hold your settings.

🔑 .secrets.toml created to hold your secrets.

🙈 the .secrets.* is also included in `.gitignore`
  beware to not push your secrets

Spend your precious time developing your application, run pip install dynaconf and let Dynaconf take care of your settings.

Quick start.

from dynaconf import settings
Enter fullscreen mode Exit fullscreen mode

And that's it!

That is the only line of code you need, no complicated boilerplate, no hadouken-ifs, no need to maintain config classes.

You must be wondering - "What magic is this? Where does the setting values come from?"

Well, there is no magic, and the values can come from wherever you want, by default and following the recommendations of the 12 factor apps Dynaconf has preference for environment variables.

# optionally you can save it in .env file
export DYNACONF_DEBUG=true
export DYNACONF_NAME=Bruno
Enter fullscreen mode Exit fullscreen mode
from dynaconf import settings
if settings.DEBUG is True:
Enter fullscreen mode Exit fullscreen mode
$ python3
Enter fullscreen mode Exit fullscreen mode

And the environment variables for Dynaconf are typed using the toml format sotrue has been evaluated to boolean True and this makes it possible to export lists, dictionaries, floats, booleans, and so on.

Read more about envvars

More than environment variables

Well, that's cool, but your project will not have settings coming from just the environment variables, I'm sure you want to have a settings file where you can set default values.

Dynaconf can read multiple file formats, out of the box it supports .py, .toml, .ini and .json. If PyYAML is installed then it will also support .yaml and you don't have to take care of finding and opening the files. The preferred format is .toml because it is currently the best configuration format, widely addopted, and you can use whatever file format you want.

# settings.toml
name = "Bruno"

debug = true

debug = false
Enter fullscreen mode Exit fullscreen mode
from dynaconf import settings
if settings.DEBUG is True:
Enter fullscreen mode Exit fullscreen mode
$ python3
Enter fullscreen mode Exit fullscreen mode

And as you can see now using settings. file we can have separate [environments] by default dynaconf will always work on [development] which means only [default] and [development] variables will be loaded. At any time you can do export ENV_FOR_DYNACONF=production and then it starts using the values from [production] environment.

If you don't want to have that separation by environment, you can simply put everything under [default] section.

Read more about environments and settings file

Some values are secrets

A good practice is to not store your secrets like passwords and tokens directly on settings files, because you can make a mistake and commit that to a public git repository, so there are some alternatives to store secrets

Environment Variables

Not recommended

There are some people who disagrees and it is really a point of security failure. However, if you are sure that your machine is protected, you can leave the secrets in the variables, at your own risk, Dynaconf can read it normally.

Secret files

This is a simple level of security for keeping secrets, and it is specially useful to keep development secrets. That token you use to access the development API etc.

It is very simple, together with your normal settings.toml you put a new file called .secrets.toml and store your sensitive data there. Dynaconf will read it after the read of the settings.toml

Wait.. how does it solve my security problem?

Well it does not (yet) but it make your life easier in 2 ways.

  1. Put .secrets.* in your ~/.gitignore so you will never commit the mistake of sending that data to a public git repository.
  2. Dynaconf can output debug information when DEBUG_LEVEL_FOR_DYNACON=DEBUG is exported, all loaded values are printed but if the values comes from a .secrets.* file, then only the key is printed and the value is masked. It is useful to use on public CI.
  3. You can setup a step on your Ansible deployment playbook that will safely copy or generate the secrets file to store there on your production environment.

You can also tell Dynaconf to load that file from somewhere else export SECRETS_FOR_DYNACONF=/path/to/secrets/location/.secrets.yaml (very useful for CI like Jenkins)

Vault Project from Hashicorp


Now we are really talking about true security

Using Vault is the better way to protect your secrets dynaconf has built-in support:

export VAULT_URL_FOR_DYNACONF=https://..../
Enter fullscreen mode Exit fullscreen mode

And then if have for example the TOKEN stores on your vault server you can simply do:

from dynaconf import settings
Enter fullscreen mode Exit fullscreen mode

Vault has lots of features like leases and sealed vaults.

Read More

Are you using Django or Flask?

Dynaconf provides extensions for those 2 frameworks, with 2 lines of code you enable it and then your framework will start reading settings from Dynaconf.


import dynaconf  # noqa
settings = dynaconf.DjangoDynaconf(__name__, **options)
Enter fullscreen mode Exit fullscreen mode

Now you if you do export DJANGO_FOO=BAR you can access inside your app via django.conf.settings.FOO

read more


from dynaconf import FlaskDynaconf
FlaskDynaconf(app, **options)
Enter fullscreen mode Exit fullscreen mode

Now you if you do export FLASK_FOO=BAR you can access inside your app via app.config['FOO']

read more

What if you are using a different settings file format? a different framework and a different external storage?

You can extend Dynaconf adding new loaders!

Dynaconf already provides loaders for:

  • .py
  • .json
  • .yaml
  • .toml
  • .ini
  • Redis Server
  • Vault Server
  • .env files
  • Environment variables

But if this is not a fit for your project you can still create your own loader


Dynaconf is the only thing you need to manage your settings!

  • Well tested
  • Trusted by companies like Red Hat, Seek, Catho and others
  • Well tested both on Linux and Windows environment
  • Strict separation of settings from code (following 12-factor applications Guide).
  • Define comprehensive default values.
  • Store parameters in multiple file formats (.toml, .json, .yaml, .ini and .py).
  • Sensitive secrets like tokens and passwords can be stored in safe places like .secrets file or vault server.
  • Parameters can optionally be stored in external services like Redis server.
  • Simple feature flag system.
  • Layered [environment] system.
  • Environment variables can be used to override parameters.
  • Support for .env files to automate the export of environment variables.
  • Correct data types (even for environment variables).
  • Have only one canonical settings module to rule all your instances.
  • Drop in extension for Flask app.config object.
  • Drop in extension for Django conf.settings object.
  • Powerful $ dynaconf CLI to help you manage your settings via console.
  • Customizable Validation System to ensure correct config parameters.
  • Allow the change of dynamic parameters on the fly without the need to redeploy your application.

Read the docs

Settings are simple but Dynaconf provides even more features like Feature Flags, Settings Context Managers, Plugin Settings etc..


Dynaconf is waiting for your feedback and Contribution


from dynaconf import settings
Enter fullscreen mode Exit fullscreen mode

Top comments (0)