Dynaconf

Warnings

• breaking The global `settings` object (`from dynaconf import settings`) is deprecated in version 3.x. You should now explicitly instantiate `Dynaconf()` to manage your settings.
  Fix: Replace `from dynaconf import settings` with `from dynaconf import Dynaconf; settings = Dynaconf(...)`. Make sure to pass your `settings_files` explicitly.
• breaking Automatic loading of settings files (e.g., `settings.toml`, `.secrets.yaml`) is disabled by default in Dynaconf 3.x. Files must now be explicitly passed via the `settings_files` argument during `Dynaconf` instantiation.
  Fix: When initializing `Dynaconf`, provide a list of your configuration files: `settings = Dynaconf(settings_files=['settings.toml', '.secrets.toml'])`.
• breaking Loading of `.env` files is disabled by default in Dynaconf 3.x.
  Fix: To enable `.env` file loading, set `load_dotenv=True` during `Dynaconf` instantiation: `settings = Dynaconf(..., load_dotenv=True)`.
• gotcha Dynaconf's path resolution relies on the Current Working Directory (CWD). Running tests or applications from an IDE that changes the CWD (e.g., PyCharm setting CWD to `./tests`) can cause `OSError: Starting path not found` as Dynaconf may fail to locate settings files.
  Fix: Ensure your IDE's run/test configuration sets the working directory to the root of your project. Alternatively, explicitly specify `root_path` when initializing `Dynaconf`.
• breaking Versions 3.2.8 and 3.2.9 were yanked from PyPI, indicating potential issues or regressions. Users should avoid these specific versions.
  Fix: Do not install or use `dynaconf==3.2.8` or `dynaconf==3.2.9`. Upgrade to `3.2.10` or later.
• breaking Templating vulnerabilities (`@jinja` and `@format`) were fixed in version 3.2.13. Older versions using these features might be susceptible to security risks. [cite: latest release notes]
  Fix: Upgrade to `dynaconf==3.2.13` or a later version to patch these vulnerabilities.

Install

• pip install dynaconf Basic Installation
• pip install dynaconf[toml,yaml,redis,vault] Installation with Optional Dependencies

Imports

• Dynaconf

  from dynaconf import Dynaconf

  The global `settings` instance is deprecated in Dynaconf 3.x. Users are encouraged to create their own `Dynaconf` instance instead.

Quickstart

This quickstart demonstrates how to initialize Dynaconf, load settings from specified TOML files (including a secrets file), and access configuration values. It highlights the importance of explicitly enabling `load_dotenv` and `environments` in version 3.x and shows how to access values, including sensitive ones, with a fallback to environment variables for production readiness.

from dynaconf import Dynaconf

# Create settings files (e.g., settings.toml and .secrets.toml)
# settings.toml:
# [default]
# FOO = 'bar'
# DATABASE_URL = 'sqlite:///mydb.sqlite'
#
# .secrets.toml:
# [default]
# API_KEY = 'secret-key-123'

settings = Dynaconf(
    envvar_prefix="DYNACONF",
    settings_files=['settings.toml', '.secrets.toml'],
    environments=True, # Enable layered environments
    load_dotenv=True # Explicitly enable .env file loading (disabled by default in 3.x)
)

# Access settings
print(f"Foo: {settings.FOO}")
print(f"Database URL: {settings.DATABASE_URL}")

# Access secret
# For production, consider using environment variables or a secure vault.
# Example: export DYNACONF_API_KEY="my_prod_api_key"
api_key = settings.get('API_KEY', os.environ.get('DYNACONF_API_KEY', 'default-api-key'))
print(f"API Key: {api_key}")

# Switch environment (e.g., in a development environment)
# export ENV_FOR_DYNACONF=development

# Example of setting a value programmatically (not persisted to file)
settings.set('NEW_SETTING', 'a new value')
print(f"New setting: {settings.NEW_SETTING}")