Free Python Hosting with Deta.sh to Get Your Code on Cloud

Intermediate

You write a FastAPI app that connects to a database and a third-party payment gateway. You hardcode the credentials during development and tell yourself you will fix it before deploying. A month later the repo is on GitHub and so is your production database password. This is not a hypothetical — it happens constantly, and it happens because os.environ.get() is clunky enough that developers avoid it until it is too late.

Python’s python-decouple library makes the right approach easier than the wrong one. It reads configuration from .env files or .ini files, applies type casting automatically, handles missing values with sensible defaults, and keeps your code clean. One pip install python-decouple is all it takes, and it works with any Python project — Flask, FastAPI, Django, or a plain script.

This article walks through everything you need to use python-decouple confidently: reading values, type casting, setting defaults, working with booleans, using .env vs .ini files, integrating with Django settings, and building a real-world config loader. By the end you will have a pattern you can drop into any project to keep secrets out of your source code for good.

Python Decouple: Quick Example

Here is a minimal working example that shows the core pattern — reading a string, an integer, and a boolean from a .env file — so you can see exactly what decouple does before we explore each feature in depth.

First, create a file named .env in your project root:

# .env
DATABASE_URL=postgresql://localhost:5432/myapp
PORT=8000
DEBUG=True
SECRET_KEY=my-local-dev-secret-key-change-in-prod

Now read those values in Python:

# quick_decouple.py
from decouple import config

# String (default type)
database_url = config('DATABASE_URL')

# Integer -- decouple casts automatically
port = config('PORT', cast=int)

# Boolean -- handles 'True', 'true', '1', 'yes', etc.
debug = config('DEBUG', cast=bool)

# String with a fallback default
secret_key = config('SECRET_KEY', default='fallback-dev-key')

print(f"DB:    {database_url}")
print(f"Port:  {port} (type: {type(port).__name__})")
print(f"Debug: {debug} (type: {type(debug).__name__})")
print(f"Key:   {secret_key[:10]}...")

Output:

DB:    postgresql://localhost:5432/myapp
Port:  8000 (type: int)
Debug: True (type: bool)
Key:   my-local-d...

Notice that port comes back as a real Python int and debug as a real bool — not strings. With os.environ you would need to write int(os.environ['PORT']) and handle the conversion yourself every time. Decouple does that work once, at the point of reading, so the rest of your code receives properly typed values.

Read on to see how decouple handles missing values, search paths, .ini files, and real-world project layouts.

What Is Python Decouple and Why Use It?

Python decouple is a library that implements the Twelve-Factor App principle of strict separation between configuration and code. Configuration here means anything that is likely to vary between deployment environments: database URLs, API keys, feature flags, port numbers, and debug settings. The idea is that these values live in the environment (a .env file locally, environment variables in production), not in the source code that gets committed to a repository.

Think of it like a restaurant kitchen. The recipes (your code) are written down and shared. The ingredients (your config values) change depending on what the supplier has that day — and the head chef does not write the supplier’s phone number into every recipe card. They keep it in a separate contact file. Decouple is that contact file system for your Python app.

Decouple vs os.environ

Here is how python-decouple compares to using os.environ directly:

The bottom line: os.environ is built-in and requires no extra dependency, but every type conversion is manual boilerplate. Decouple pays for itself the moment you have more than two or three config values that need casting.

Installing python-decouple

Install it with pip in your virtual environment:

# install_decouple.py (run this in your terminal, not as a script)
pip install python-decouple

Output:

Successfully installed python-decouple-3.8

There is one important naming note: the library is called python-decouple on PyPI (what you install), but the import name is decouple (what you use in code). Do not confuse it with decouple on PyPI — that is a different package for Django-specific use. Always install python-decouple.

The .env File: Format and Best Practices

A .env file is a plain text file with one KEY=value pair per line. Decouple searches for it starting in the directory of the script being run, then walks up to parent directories. This means you can place it at the root of your project and it will be found regardless of which subdirectory you run from.

# .env  (place this in your project root)

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp_dev

# Server
PORT=8000
HOST=0.0.0.0

# Feature flags
DEBUG=True
ENABLE_CACHING=False

# Third-party APIs
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xyz789

# Email
EMAIL_BACKEND=console
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587

There are a few formatting rules to know. Values do not need quotes — DEBUG=True works fine. If your value contains spaces or special characters, wrap it in single or double quotes: FULL_NAME='Ada Lovelace'. Lines starting with # are comments and are ignored. Empty lines are also ignored.

The most important rule: add .env to your .gitignore immediately. Create a .env.example file with the same keys but dummy values, and commit that instead. New developers clone the repo, copy .env.example to .env, fill in their local values, and they are ready to go.

Type Casting with cast=

Every value in a .env file is stored as a string. Decouple’s cast parameter converts the string to the type you need before returning it, so the rest of your code never sees a string where it expects an integer or boolean.

Integers and Floats

Pass cast=int or cast=float to convert numeric config values. This is far cleaner than wrapping every read in a manual conversion.

# cast_examples.py
from decouple import config

# These values exist in .env:
# PORT=8000
# WORKERS=4
# TIMEOUT=30.5

port = config('PORT', default=8000, cast=int)
workers = config('WORKERS', default=2, cast=int)
timeout = config('TIMEOUT', default=30.0, cast=float)

print(f"Port:    {port}  -- {type(port).__name__}")
print(f"Workers: {workers}  -- {type(workers).__name__}")
print(f"Timeout: {timeout}  -- {type(timeout).__name__}")

Output:

Port:    8000  -- int
Workers: 4  -- int
Timeout: 30.5  -- float

If the .env value cannot be cast to the requested type — for example, PORT=eight_thousand — decouple raises a ValueError with a clear message pointing to the offending key. You get the error at startup when reading config, not somewhere deep in your app when the value is used.

Booleans

Boolean config values are tricky with os.environ because every string is truthy. "False" evaluates to True in Python because it is a non-empty string. Decouple’s boolean cast handles this correctly by recognizing a set of canonical true and false values.

# cast_bool.py
from decouple import config

# .env contains:
# DEBUG=True
# ENABLE_CACHING=False
# USE_SSL=yes
# MAINTENANCE_MODE=0

debug = config('DEBUG', cast=bool)
caching = config('ENABLE_CACHING', cast=bool)
ssl = config('USE_SSL', cast=bool)
maintenance = config('MAINTENANCE_MODE', cast=bool)

print(f"DEBUG:            {debug}")
print(f"ENABLE_CACHING:   {caching}")
print(f"USE_SSL:          {ssl}")
print(f"MAINTENANCE_MODE: {maintenance}")

Output:

DEBUG:            True
ENABLE_CACHING:   False
USE_SSL:          True
MAINTENANCE_MODE: False

The recognized truthy values are True, true, 1, yes, on. The recognized falsy values are False, false, 0, no, off. Anything else raises a ValueError. This strict set prevents the bug where DEBUG=False still evaluates to True because you forgot to cast.

Comma-Separated Lists

Decouple does not have a built-in list type, but you can pass any callable as the cast argument — including a lambda that splits a string into a list.

# cast_list.py
from decouple import config, Csv

# .env contains:
# ALLOWED_HOSTS=localhost,127.0.0.1,myapp.com
# CORS_ORIGINS=http://localhost:3000,https://app.example.com

# Option 1: built-in Csv helper (strips whitespace, handles quoting)
allowed_hosts = config('ALLOWED_HOSTS', cast=Csv())

# Option 2: lambda for simple cases
cors_origins = config('CORS_ORIGINS', default='', cast=lambda v: [s.strip() for s in v.split(',')])

print(f"Allowed hosts: {allowed_hosts}")
print(f"CORS origins:  {cors_origins}")

Output:

Allowed hosts: ['localhost', '127.0.0.1', 'myapp.com']
CORS origins:  ['http://localhost:3000', 'https://app.example.com']

The Csv() helper from decouple is the cleaner option for comma-separated values. It handles edge cases like extra whitespace and quoted values with commas inside them. The lambda approach works fine for simple cases where you control the format.

Defaults and Missing Values

When a key is missing from both the .env file and the actual environment, decouple’s behavior depends on whether you provided a default.

# defaults_demo.py
from decouple import config, UndefinedValueError

# KEY_WITH_DEFAULT is not in .env -- returns the default
log_level = config('LOG_LEVEL', default='INFO')
print(f"Log level: {log_level}")

# KEY_WITH_NONE_DEFAULT is not in .env -- returns None
cache_url = config('CACHE_URL', default=None)
print(f"Cache URL: {cache_url}")

# KEY_REQUIRED is not in .env and has no default -- raises UndefinedValueError
try:
    api_key = config('REQUIRED_API_KEY')
except UndefinedValueError as e:
    print(f"Missing required config: {e}")

Output:

Log level: INFO
Cache URL: None
Missing required config: REQUIRED_API_KEY not found. Declare it as envvar or define a default value.

This behavior is intentional and useful. Required values — things your app absolutely cannot run without — should have no default. That way decouple raises a clear error at startup rather than letting the app start in a broken state and fail later with a cryptic message. Optional values should have a sensible default so the app can run in a minimal configuration without a full .env file in place.

.ini File Support

In addition to .env files, decouple can read from .ini files using the AutoConfig or explicit RepositoryIni approach. This is useful when your project already has a settings.ini or setup.cfg and you do not want to introduce a second config file.

# settings.ini
[settings]
DATABASE_URL=postgresql://localhost:5432/myapp
PORT=8000
DEBUG=True

# read_ini.py
from decouple import Config, RepositoryIni

# Explicitly read from a .ini file instead of .env
config = Config(RepositoryIni('settings.ini'))

database_url = config('DATABASE_URL')
port = config('PORT', cast=int)
debug = config('DEBUG', cast=bool)

print(f"DB:    {database_url}")
print(f"Port:  {port}")
print(f"Debug: {debug}")

Output:

DB:    postgresql://localhost:5432/myapp
Port:  8000
Debug: True

The default config object (imported directly from decouple) uses AutoConfig, which searches for .env first, then .ini, then falls back to actual environment variables. You only need to use RepositoryIni explicitly when you want to force a specific file rather than letting decouple search.

Django Integration

Django’s settings.py is the most common place developers accidentally commit secrets. Decouple is designed to slot in cleanly as a drop-in replacement for hardcoded settings.

# settings.py (Django)
from decouple import config, Csv

# Core Django settings
SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', cast=bool, default=False)
ALLOWED_HOSTS = config('ALLOWED_HOSTS', cast=Csv(), default='localhost')

# Database -- dj-database-url makes this even cleaner
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('DB_NAME', default='myapp'),
        'USER': config('DB_USER', default='postgres'),
        'PASSWORD': config('DB_PASSWORD', default=''),
        'HOST': config('DB_HOST', default='localhost'),
        'PORT': config('DB_PORT', default=5432, cast=int),
    }
}

# Email
EMAIL_BACKEND = config('EMAIL_BACKEND', default='django.core.mail.backends.console.EmailBackend')
EMAIL_HOST = config('EMAIL_HOST', default='localhost')
EMAIL_PORT = config('EMAIL_PORT', default=25, cast=int)
EMAIL_USE_TLS = config('EMAIL_USE_TLS', cast=bool, default=False)

# Stripe
STRIPE_PUBLIC_KEY = config('STRIPE_PUBLIC_KEY', default='')
STRIPE_SECRET_KEY = config('STRIPE_SECRET_KEY', default='')

The pattern is consistent throughout: use config('KEY') for required values that must exist in production, and config('KEY', default=...) for optional values with safe development defaults. The entire settings.py file becomes safe to commit because it contains no actual secrets — just the names of the keys and their defaults.

Real-Life Example: Environment-Aware FastAPI App

Here is a realistic FastAPI application config module that uses decouple to manage all its settings. This pattern — a dedicated config.py module that gathers all config into a dataclass — scales cleanly as the project grows.

# config.py
from dataclasses import dataclass
from decouple import config, Csv, UndefinedValueError

@dataclass
class AppConfig:
    # Server
    host: str
    port: int
    debug: bool
    workers: int

    # Database
    database_url: str

    # Security
    secret_key: str
    allowed_origins: list

    # External APIs
    stripe_secret_key: str
    sendgrid_api_key: str
    slack_webhook_url: str

    # Feature flags
    enable_caching: bool
    enable_email: bool

def load_config() -> AppConfig:
    """Load and validate all application configuration at startup."""
    return AppConfig(
        # Server
        host=config('HOST', default='0.0.0.0'),
        port=config('PORT', default=8000, cast=int),
        debug=config('DEBUG', default=False, cast=bool),
        workers=config('WORKERS', default=1, cast=int),

        # Database -- required in production, no default
        database_url=config('DATABASE_URL'),

        # Security -- required always
        secret_key=config('SECRET_KEY'),
        allowed_origins=config('ALLOWED_ORIGINS', cast=Csv(), default='http://localhost:3000'),

        # External APIs -- optional with empty defaults (check before use)
        stripe_secret_key=config('STRIPE_SECRET_KEY', default=''),
        sendgrid_api_key=config('SENDGRID_API_KEY', default=''),
        slack_webhook_url=config('SLACK_WEBHOOK_URL', default=''),

        # Feature flags
        enable_caching=config('ENABLE_CACHING', default=False, cast=bool),
        enable_email=config('ENABLE_EMAIL', default=False, cast=bool),
    )

# main.py
from fastapi import FastAPI
from config import load_config, AppConfig

cfg: AppConfig = load_config()  # Fails fast at startup if required vars missing
app = FastAPI(debug=cfg.debug)

@app.get("/health")
def health():
    return {
        "status": "ok",
        "debug": cfg.debug,
        "caching": cfg.enable_caching,
        "port": cfg.port,
    }

if __name__ == "__main__":
    import uvicorn
    print(f"Starting on {cfg.host}:{cfg.port} (debug={cfg.debug})")
    uvicorn.run(app, host=cfg.host, port=cfg.port, workers=cfg.workers)

Output (with example .env values):

Starting on 0.0.0.0:8000 (debug=False)

The key design choice here is that load_config() is called once at module level, so any missing required variable raises UndefinedValueError the moment the app starts — not on the first request five minutes into a production deploy. The dataclass gives you IDE autocomplete throughout the rest of the codebase and makes it obvious what configuration the app expects without opening the .env file.

Testing with Decouple

Config management and testability often conflict — tests need predictable values, but decouple reads from files. There are two clean approaches: use a test-specific .env file, or monkeypatch os.environ.

# test_config.py
import os
import pytest
from unittest.mock import patch

# Approach 1: patch os.environ before importing config
def test_debug_defaults_to_false():
    with patch.dict(os.environ, {'DATABASE_URL': 'sqlite:///test.db', 'SECRET_KEY': 'test-key'}, clear=True):
        # Reimport or reload config within the patch context
        from decouple import config
        # config() reads os.environ after checking .env
        debug = config('DEBUG', default=False, cast=bool)
        assert debug is False

def test_port_casting():
    with patch.dict(os.environ, {'PORT': '9000'}):
        from decouple import config
        port = config('PORT', cast=int)
        assert port == 9000
        assert isinstance(port, int)

def test_missing_required_raises():
    from decouple import config, UndefinedValueError
    with patch.dict(os.environ, {}, clear=True):
        # Remove DATABASE_URL from the environment
        env_without_db = {k: v for k, v in os.environ.items() if k != 'DATABASE_URL'}
        with patch.dict(os.environ, env_without_db, clear=True):
            with pytest.raises(UndefinedValueError):
                config('DATABASE_URL')

Output (pytest):

...
3 passed in 0.12s

The recommended approach for larger projects is to create a .env.test file and use a fixture that temporarily swaps the decouple search path to point at it. This gives you a full, realistic config setup for tests without polluting your development .env. The patch.dict(os.environ, ...)` approach shown above works well for unit tests of individual config values.