{"id":1677,"library":"python-decouple","title":"python-decouple","description":"python-decouple provides a clean, strict separation of configuration settings from code, inspired by The Twelve-Factor App methodology. It allows you to store parameters in environment variables, `.env` files, or `settings.ini` files, making it easy to manage different environments (development, staging, production). The current version is 3.8, and it sees active maintenance with minor releases typically a few times a year addressing bug fixes and minor improvements.","status":"active","version":"3.8","language":"en","source_language":"en","source_url":"https://github.com/henriquebastos/python-decouple/","tags":["configuration","settings","environment variables","dotenv","ini","twelve-factor-app"],"install":[{"cmd":"pip install python-decouple","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"While `Config` class exists, the primary high-level helper is `decouple.config` imported directly from the top-level package.","wrong":"from decouple.config import config","symbol":"config","correct":"from decouple import config"},{"symbol":"AutoConfig","correct":"from decouple import AutoConfig"}],"quickstart":{"code":"import os\nfrom decouple import config\n\n# Create a dummy .env file for demonstration\nwith open('.env', 'w') as f:\n    f.write('DATABASE_URL=postgres://user:pass@host:5432/dbname\\n')\n    f.write('DEBUG=True\\n')\n    f.write('SECRET_KEY=\"my_secret_key\"\\n')\n    f.write('ALLOWED_HOSTS=localhost,127.0.0.1\\n')\n\n# Read a setting from .env or environment variable\ndb_url = config('DATABASE_URL')\nprint(f\"Database URL: {db_url}\")\n\n# Read a boolean setting, casting it\ndebug = config('DEBUG', cast=bool)\nprint(f\"Debug mode: {debug} (type: {type(debug)})\")\n\n# Read a string with a default value if not found\napi_key = config('API_KEY', default='default_api_key')\nprint(f\"API Key: {api_key}\")\n\n# Read a list using Csv cast\nhosts = config('ALLOWED_HOSTS', cast=lambda v: v.split(','))\nprint(f\"Allowed Hosts: {hosts} (type: {type(hosts)})\")\n\n# Clean up the dummy .env file\nos.remove('.env')","lang":"python","description":"This quickstart demonstrates how to use `decouple.config` to load settings from a `.env` file (or environment variables). It shows retrieving a simple string, casting a boolean, providing a default value, and parsing a comma-separated string into a list using a custom cast function. `decouple` automatically looks for `.env` or `settings.ini` files in the current directory or parent directories."},"warnings":[{"fix":"Always provide a `default` parameter to `config()` (e.g., `config('MY_KEY', default=None)`) or ensure the key exists in your `settings.ini` file if you were relying on implicit `None` returns for missing INI keys.","message":"In `v3.8`, accessing keys that are not found within INI repositories will now strictly raise a `KeyError` by default, rather than silently failing or returning `None`.","severity":"breaking","affected_versions":">=3.8"},{"fix":"Always explicitly provide a `default` value if a setting is optional (e.g., `config('OPTIONAL_KEY', default=None)`). Otherwise, ensure all required settings are defined in your environment or configuration files.","message":"If a setting is not found in any repository (environment variables, `.env`, `settings.ini`) and no `default` value is provided, `config()` will raise an `UndefinedValueError`. This is a core design principle of `decouple` to ensure strictness.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `v3.7` or later. If upgrading is not immediately possible, avoid using `Csv` or similar string-splitting casts with `default=None` in older versions. Instead, provide an empty list as a default: `config('MY_LIST', cast=Csv(), default=[])`.","message":"The `Csv` cast function (or any custom cast that splits a string) when used with `default=None` in `v3.6` and earlier could result in an infinite hang. This was fixed in `v3.7`.","severity":"gotcha","affected_versions":"<3.7"},{"fix":"Be mindful of where you define your settings. For local development, `.env` is often preferred. For production, environment variables are typically used. Ensure you're not inadvertently overriding critical settings with lower-precedence definitions.","message":"python-decouple loads settings in a specific order of precedence: Environment variables take highest priority, followed by `.env` files, and then `settings.ini` files. If a setting is defined in multiple places, the one with higher precedence will be used.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}