Python Decouple¶
- Authors:
Wendyam YAMEOGO <yameogoivan10@gmail.com>
- Version:
2025-08
source: https://pypi.org/project/python-decouple/
That is a new way of handling either your environment variables or your configuration files.
Python Decouple helps you to separate settings from code. It allows you to define your settings in environment variables .env or µ.ini files, and then access them in your Python code.
Example of .env file:
DEBUG=True
TEMPLATE_DEBUG=True
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%
#COMMENTED=42 <- this is a commented line
Example of a settings.ini file:
[settings]
DEBUG=True
TEMPLATE_DEBUG=%(DEBUG)s
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%%
#COMMENTED=42 <- this is a commented line
To use Python Decouple, you need to install it first. You can do this using pip:
pip install python-decouple
Then, you can use it in your Python code like this:
from decouple import config, Csv
DEBUG = config('DEBUG', default=False, cast=bool)
TEMPLATE_DEBUG = config('TEMPLATE_DEBUG', default=DEBUG, cast=bool)
SECRET_KEY = config('SECRET_KEY')
DATABASE_URL = config('DATABASE_URL')
PERCENTILE = config('PERCENTILE', default=90, cast=int)
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='localhost', cast=Csv())
TIMEOUT = config('TIMEOUT', default=5.0, cast=float)
Focus on the cast parameter¶
It allows you to specify the type of the variable you want to retrieve.
Example of usage of the cast parameter:
>>> os.environ['DEBUG'] = 'False'
>>> config('DEBUG', cast=bool)
False
>>> os.environ['EMAIL_PORT'] = '42'
>>> config('EMAIL_PORT', cast=int)
42
>>> os.environ['ALLOWED_HOSTS'] = '.localhost, .herokuapp.com'
>>> config('ALLOWED_HOSTS', cast=lambda v: [s.strip() for s in v.split(',')])
['.localhost', '.herokuapp.com']
>>> os.environ['SECURE_PROXY_SSL_HEADER'] = 'HTTP_X_FORWARDED_PROTO, https'
>>> config('SECURE_PROXY_SSL_HEADER', cast=Csv(post_process=tuple))
('HTTP_X_FORWARDED_PROTO', 'https')
>>> os.environ['LIST_OF_INTEGERS'] = '1,2,3,4,5'
>>> config('LIST_OF_INTEGERS', cast=Csv(int))
[1, 2, 3, 4, 5]
>>> os.environ['COMPLEX_STRING'] = '%virtual_env%\t *important stuff*\t trailing spaces '
>>> csv = Csv(cast=lambda s: s.upper(), delimiter='\t', strip=' %*')
>>> csv(os.environ['COMPLEX_STRING'])
['VIRTUAL_ENV', 'IMPORTANT STUFF', 'TRAILING SPACES']
Choices Helper¶
Allows for cast and validation based on a list of choices. For example:
>>> from decouple import config, Choices
>>> os.environ['CONNECTION_TYPE'] = 'usb'
>>> config('CONNECTION_TYPE', cast=Choices(['eth', 'usb', 'bluetooth']))
'usb'
>>> os.environ['CONNECTION_TYPE'] = 'serial'
>>> config('CONNECTION_TYPE', cast=Choices(['eth', 'usb', 'bluetooth']))
Traceback (most recent call last):
...
ValueError: Value not in list: 'serial'; valid values are ['eth', 'usb', 'bluetooth']
>>> os.environ['SOME_NUMBER'] = '42'
>>> config('SOME_NUMBER', cast=Choices([7, 14, 42], cast=int))
42
Important
Why use Python Decouple and not just os.environ ?
Note