Python Dynaconf Settings — Core Concepts

Why this topic matters

Applications need different settings for development, testing, staging, and production. Managing this across file formats, environment variables, and secrets stores creates fragmented configuration logic. Dynaconf unifies these sources into a single settings object with environment switching, validation, and live reloading — without requiring changes to your application code.

How it works

Install Dynaconf and initialize it in your project:

pip install dynaconf
dynaconf init -f toml

This creates a settings structure:

settings.toml       # Default settings
.secrets.toml       # Sensitive values (gitignored)

Access settings anywhere in your code:

from dynaconf import settings

print(settings.DATABASE_URL)
print(settings.get("CACHE_TTL", 300))

Settings files use environment sections:

[default]
database_url = "sqlite:///dev.db"
debug = true

[production]
database_url = "postgresql://prod-server/app"
debug = false

Switch environments via the ENV_FOR_DYNACONF variable:

ENV_FOR_DYNACONF=production python app.py

Key concepts

Multi-source layering

Dynaconf reads from multiple sources in priority order:

1. Defaults defined in code
2. Settings files (TOML, YAML, JSON, INI, or Python)
3. Environment-specific sections within those files
4. .secrets files for sensitive data
5. Environment variables prefixed with DYNACONF_
6. External loaders (Redis, Vault, custom)

Higher-priority sources override lower ones. An environment variable DYNACONF_DATABASE_URL=postgres://new overrides what’s in settings.toml.

Environment variables with prefixes

Dynaconf uses the DYNACONF_ prefix to avoid clashing with system variables:

export DYNACONF_API_KEY="sk-prod-key"
export DYNACONF_MAX_RETRIES=5
export DYNACONF_DEBUG="@bool false"

The @bool, @int, @json type markers handle type casting — environment variables are always strings, but your code gets proper Python types.

Settings validation

Define validation rules that run at startup:

from dynaconf import Dynaconf, Validator

settings = Dynaconf(
    settings_files=["settings.toml"],
    validators=[
        Validator("DATABASE_URL", must_exist=True),
        Validator("DEBUG", is_type_of=bool, default=False),
        Validator("CACHE_TTL", gte=60, lte=3600),
        Validator("API_KEY", must_exist=True, when=Validator("ENV_FOR_DYNACONF", eq="production")),
    ],
)
settings.validators.validate()

This catches misconfiguration at startup rather than at runtime — especially valuable for production deployments.

Live reloading

Dynaconf can reload settings without restarting:

settings.reload()

For long-running services, this lets operators change feature flags or thresholds by editing a settings file and triggering a reload — useful for gradual rollouts or emergency configuration changes.

Framework integration

Dynaconf provides first-class support for Django and Flask:

# Flask
from dynaconf import FlaskDynaconf
app = Flask(__name__)
FlaskDynaconf(app, settings_files=["settings.toml"])

# Django — in settings.py
import dynaconf
settings = dynaconf.DjangoDynaconf(__name__)

These integrations wire into the framework’s own settings mechanism, so existing code that reads app.config["KEY"] or django.conf.settings.KEY works without modification.

Common misconception

“Dynaconf is just python-dotenv with extra steps.” While both handle environment-based config, Dynaconf provides structured environments, typed validation, secrets file separation, live reloading, and external vault integration. It’s a full configuration management system, not just an env-file loader.

One thing to remember

Dynaconf layers settings from files, environment variables, and secrets stores into a single validated object — letting you switch environments with one variable and catch misconfigurations before they cause runtime failures.