# python-decouple > Strict separation of settings from code. - **URL**: https://www.freshcrate.ai/projects/python-decouple - **Author**: Henrique Bastos - **Category**: Frameworks - **Latest version**: `3.8` (2026-04-21) - **License**: MIT - **Source**: http://github.com/henriquebastos/python-decouple/ - **Language**: Python - **GitHub**: 3,031 stars, 216 forks - **Registry**: pypi (`python-decouple`) - **Tags**: `pypi` ## Description Python Decouple: Strict separation of settings from code ======================================================== *Decouple* helps you to organize your settings so that you can change parameters without having to redeploy your app. It also makes it easy for you to: #. store parameters in *ini* or *.env* files; #. define comprehensive default values; #. properly convert values to the correct data type; #. have **only one** configuration module to rule all your instances. It was originally designed for Django, but became an independent generic tool for separating settings from code. .. image:: https://img.shields.io/travis/henriquebastos/python-decouple.svg :target: https://travis-ci.org/henriquebastos/python-decouple :alt: Build Status .. image:: https://img.shields.io/pypi/v/python-decouple.svg :target: https://pypi.python.org/pypi/python-decouple/ :alt: Latest PyPI version .. contents:: Summary Why? ==== The settings files in web frameworks store many different kinds of parameters: * Locale and i18n; * Middlewares and Installed Apps; * Resource handles to the database, Memcached, and other backing services; * Credentials to external services such as Amazon S3 or Twitter; * Per-deploy values such as the canonical hostname for the instance. The first 2 are *project settings* and the last 3 are *instance settings*. You should be able to change *instance settings* without redeploying your app. Why not just use environment variables? --------------------------------------- *Envvars* works, but since ``os.environ`` only returns strings, it's tricky. Let's say you have an *envvar* ``DEBUG=False``. If you run: .. code-block:: python if os.environ['DEBUG']: print True else: print False It will print **True**, because ``os.environ['DEBUG']`` returns the **string** ``"False"``. Since it's a non-empty string, it will be evaluated as True. *Decouple* provides a solution that doesn't look like a workaround: ``config('DEBUG', cast=bool)``. Usage ===== Install: .. code-block:: console pip install python-decouple Then use it on your ``settings.py``. #. Import the ``config`` object: .. code-block:: python from decouple import config #. Retrieve the configuration parameters: .. code-block:: python SECRET_KEY = config('SECRET_KEY') DEBUG = config('DEBUG', default=False, cast=bool) EMAIL_HOST = config('EMAIL_HOST', default='localhost') EMAIL_PORT = config('EMAIL_PORT', default=25, cast=int) Encodings --------- Decouple's default encoding is `UTF-8`. But you can specify your preferred encoding. Since `config` is lazy and only opens the configuration file when it's first needed, you have the chance to change its encoding right after import. .. code-block:: python from decouple import config config.encoding = 'cp1251' SECRET_KEY = config('SECRET_KEY') If you wish to fall back to your system's default encoding use: .. code-block:: python import locale from decouple import config config.encoding = locale.getpreferredencoding(False) SECRET_KEY = config('SECRET_KEY') Where is the settings data stored? ----------------------------------- *Decouple* supports both *.ini* and *.env* files. Ini file ~~~~~~~~ Simply create a ``settings.ini`` next to your configuration module in the form: .. code-block:: ini [settings] DEBUG=True TEMPLATE_DEBUG=%(DEBUG)s SECRET_KEY=ARANDOMSECRETKEY DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase PERCENTILE=90%% #COMMENTED=42 *Note*: Since ``ConfigParser`` supports *string interpolation*, to represent the character ``%`` you need to escape it as ``%%``. Env file ~~~~~~~~ Simply create a ``.env`` text file in your repository's root directory in the form: .. code-block:: console DEBUG=True TEMPLATE_DEBUG=True SECRET_KEY=ARANDOMSECRETKEY DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase PERCENTILE=90% #COMMENTED=42 Example: How do I use it with Django? ------------------------------------- Given that I have a ``.env`` file in my repository's root directory, here is a snippet of my ``settings.py``. I also recommend using `pathlib `_ and `dj-database-url `_. .. code-block:: python # coding: utf-8 from decouple import config from unipath import Path from dj_database_url import parse as db_url BASE_DIR = Path(__file__).parent DEBUG = config('DEBUG', default=False, cast=bool) TEMPLATE_DEBUG = DEBUG DATABASES = { 'default': config( 'DATABASE_URL', default='sqlite:///' + BASE_DIR.child('db.sqlite3'), cast=db_url ) } TIME_ZONE = 'America/Sao_Paulo' USE_L10N = True USE_TZ = True SECRET_KEY = config('SECRET_KEY') EMAIL_HOST = config('EMAIL_HOST', default='localhost') EMAIL_PORT = config ## Recent releases | Version | Date | Urgency | Changes | | --- | --- | --- | --- | | `3.8` | 2026-04-21 | Low | Imported from PyPI (3.8) | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | | `v3.8` | 2023-03-01 | Low | ## What's Changed * Raise KeyError when key is not found in ini repositories by @b0o in https://github.com/HBNetwork/python-decouple/pull/153 * Fix infinite recursion on Windows by @ibachar-es in https://github.com/HBNetwork/python-decouple/pull/137 ## New Contributors * @b0o made their first contribution in https://github.com/HBNetwork/python-decouple/pull/153 * @ibachar-es made their first contribution in https://github.com/HBNetwork/python-decouple/pull/137 **Full Changelog**: https | ## Citation - HTML: https://www.freshcrate.ai/projects/python-decouple - Markdown: https://www.freshcrate.ai/projects/python-decouple.md - Dependencies JSON: https://www.freshcrate.ai/api/projects/python-decouple/deps _Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._