dynaconf

library3.3.5pypypi✓ verified 29d ago

Dynaconf is a dynamic configuration management library for Python projects, inspired by the 12-factor application guide. It supports multiple file formats (TOML, YAML, JSON, INI, Python), environment variables, Hashicorp Vault, and Redis for settings and secrets. It provides a flexible, layered system for multi-environment configurations and includes built-in extensions for Flask and Django. The library is actively maintained, with the current version being 3.2.13, and receives regular updates and bug fixes.

devops serialization web-framework database

pip install dynaconf

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DYNACONF

dynaconf

devopspythonv3.3.5

Install

2.6s avg

Import

239ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.3.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.255s · 31.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.6s · import 0.223s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Dynaconf

✓ from dynaconf import Dynaconf

✗ from dynaconf import settings

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

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}")

dynaconf --version

Debug

Known issues

breakingThe 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.

affects: >=3.0.0

breakingAutomatic 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'])`.

affects: >=3.0.0

breakingLoading 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)`.

affects: >=3.0.0

gotchaDynaconf'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`.

affects: All versions

breakingVersions 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.

affects: 3.2.8, 3.2.9

breakingTemplating 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.

affects: <3.2.13

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dynaconf'

The 'dynaconf' library has not been installed in the current Python environment.

fix

pip install dynaconf

AttributeError: 'Settings' object has no attribute 'MY_KEY'

Dynaconf cannot find the requested setting 'MY_KEY'. This can be due to incorrect file loading paths, a missing environment variable, or accessing a key in a non-active environment or scope.

fix

Ensure Dynaconf is initialized with the correct `settings_files` and `root_path`. If using layered environments, set `environments=True` in `Dynaconf()` and verify the `ENV_FOR_DYNACONF` environment variable or `env` argument. For nested keys, use dot notation (e.g., `settings.SECTION.MY_KEY`).

OSError: Starting path not found

Dynaconf's path resolution for settings files often relies on the Current Working Directory (CWD), which can be altered by IDEs or specific test runners, preventing it from finding your configuration files.

fix

Explicitly define the `root_path` in your `Dynaconf` instance using an absolute path (e.g., `Dynaconf(root_path=os.path.dirname(os.path.abspath(__file__)))`), or configure your IDE's run/debug settings to set the working directory to your project's root.

ValidationError

A validation rule defined using Dynaconf's `Validator` feature has failed, indicating that a setting's value does not meet the specified criteria (e.g., `must_exist`, `is_type`, equality conditions, or custom functions).

fix

Review the setting's value to ensure it complies with the associated validator's conditions, or adjust the validator definition if its requirements are not correct for the intended configuration.

Upgrade

Version history

3.3.5latest on PyPI · released Aug 5, 2026

Audit

Dependencies

redisoptionalFor Redis backend support.

hvacoptionalFor Hashicorp Vault backend support (installed via [vault] extra).

ruamel.yamloptionalFor YAML file support (installed via [yaml] extra).

tomloptionalFor TOML file support (installed via [toml] extra).

configobjoptionalFor INI file support (installed via [ini] extra).

Agent activity

30 hits · last 30 days

node

Resources

githubhttps://github.com/dynaconf/dynaconf ↗

packagehttps://pypi.org/project/dynaconf/ ↗

homepagehttps://www.dynaconf.com ↗