---
id: python-decouple
version: "3.8"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# python-decouple — Strict separation of settings from code.

License: permissive · Maintenance: dormant · Downloads: 8.8M/mo

## What it is and what it does

Python Decouple is a configuration management library that reads settings from environment variables, .env files, or ini files and makes them available to your Python code with optional type casting and default values. It solves the problem that environment variables are always strings—if you read DEBUG=False from an environment variable, a simple truthiness check will treat it as True because the string "False" is non-empty. Decouple lets you cast values to the correct type (bool, int, list, etc.) and define sensible defaults, so your code can safely assume the right data types.

Originally designed for Django, it has become a framework-agnostic tool used across web frameworks and general Python applications. It respects Unix convention by checking environment variables first, then falling back to config files, then to defaults you provide. The library is lazy—it only opens and parses config files when first needed—and supports UTF-8 encoding by default with the option to specify another.

Use it for:

- Store database credentials, API keys, and service URLs in .env files without committing them to version control.
- Toggle DEBUG mode and feature flags between development, staging, and production without redeploying code.
- Configure email, cache, and logging backends with environment-specific values in Django or Flask settings.
- Cast port numbers, timeouts, and batch sizes from environment strings to integers in application initialization.
- Define per-deployment hostnames and SSL settings that change between instances without code changes.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Reads configuration parameters from environment variables, .env files, or ini files, with type casting and default values, keeping settings separate from code.

Yes. This is a mature, stable library with no dependencies, low install friction, and no known vulnerabilities. It solves a real problem (type-safe configuration from environment) that most Python applications face. The dormant maintenance status is not a concern for a small, focused tool that does one thing well and has been Production/Stable since 2014. Install it if you need to manage settings separately from code.

## Install

pip install python-decouple
uv add python-decouple
poetry add python-decouple

## Installing python-decouple

Before you install: Low install friction with no runtime dependencies. Maintenance is dormant (last release 2023-03-01, 1262 days ago), but the package is marked Production/Stable and has accumulated 3039 repository stars, suggesting it is mature and widely relied upon despite infrequent updates.

License in practice: MIT license is permissive, allowing commercial and private use with minimal restrictions—you may use, modify, and distribute the package freely provided you include the license notice.

Quickstart:

pip install python-decouple

from decouple import config

DEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')
EMAIL_PORT = config('EMAIL_PORT', default=25, cast=int)

Verify before relying:

- Whether the package actively maintains compatibility with modern Python versions beyond what classifiers indicate.
- Performance characteristics when reading large numbers of configuration parameters.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 8.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

environment variable configuration, settings management from env files, config casting and defaults, .env file loader, separate settings from code, configuration management python, environment-based config, configuration-management, environment-variables, settings-framework

[View on SkillFed](https://skillfed.io/packages/python-decouple) · [View on PyPI](https://pypi.org/project/python-decouple/)