Install & Compatibility
Where this runs
tested against v0.14.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.062s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.054s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Env
✓ from environ import Env
Path
✓ from environ import Path
Used for path handling, typically to define BASE_DIR, etc.
InvalidPathSetting
✓ from environ import InvalidPathSetting
An exception that can be caught when path-related settings are invalid.
This quickstart demonstrates how to initialize `django-environ`, set up default type casting, and access various types of environment variables including complex ones like database and cache URLs. It simulates environment variables for a runnable example without requiring a physical `.env` file to be present.
import environ
import os
# --- Simulate environment variables for a runnable example ---
# In a real application, these would come from your actual .env file or OS environment.
# For local testing, you might create a .env file like:
# SECRET_KEY=your-super-secret-key-from-env
# DEBUG=True
# DATABASE_URL=sqlite:///myproject.sqlite3
# EMAIL_URL=smtp://user:password@smtp.example.com:587
# CACHE_URL=redis://localhost:6379/1
# ------------------------------------------------------------
os.environ.setdefault('SECRET_KEY', 'your-super-secret-key-for-dev-fallback')
os.environ.setdefault('DEBUG', 'True')
os.environ.setdefault('DATABASE_URL', 'sqlite:///myproject.sqlite3')
os.environ.setdefault('EMAIL_URL', 'smtp://user:password@smtp.example.com:587')
os.environ.setdefault('CACHE_URL', 'redis://localhost:6379/1')
# Initialize the Env object.
# You can set default types and values here if not found in .env or os.environ.
env = environ.Env(
# default type for DEBUG is bool, default value is False if not set
DEBUG=(bool, False)
)
# Optional: Explicitly read .env file. By default, Env.read_env() looks for .env
# in the current directory and its parents. If you don't call this, it implicitly
# reads it on the first call to env() or similar, but explicit is better for control.
# Note: This line assumes a .env file exists. For this example, we're relying on os.environ.setdefault.
# environ.Env.read_env()
# Accessing environment variables with type casting
SECRET_KEY = env('SECRET_KEY')
DEBUG = env('DEBUG') # Uses the (bool, False) casting defined above
# Complex settings like database or cache URLs are parsed into Django-compatible dictionaries
DATABASES = {
'default': env.db() # uses DATABASE_URL from environment
}
CACHES = {
'default': env.cache() # uses CACHE_URL from environment
}
EMAIL = env.email() # uses EMAIL_URL from environment
print(f"SECRET_KEY: {SECRET_KEY}")
print(f"DEBUG: {DEBUG} (type: {type(DEBUG)})")
print(f"DATABASES (default): {DATABASES['default']}")
print(f"CACHES (default): {CACHES['default']}")
print(f"EMAIL (default): {EMAIL}")
# Example of a missing variable with a default
APP_VERSION = env('APP_VERSION', default='1.0.0')
print(f"APP_VERSION: {APP_VERSION}")
Errors
Common errors & fixes
django.core.exceptions.ImproperlyConfigured: Set the SECRET_KEY environment variable
This error occurs when `django-environ` cannot find the specified environment variable (e.g., `SECRET_KEY`) because it's missing from the `.env` file, the `.env` file isn't being read, or an existing environment variable is not being overridden.
fixEnsure a `.env` file exists in your project's root directory (or the path specified for `read_env()`). Verify that the variable (e.g., `SECRET_KEY`) is present in the `.env` file with a value. Confirm that `environ.Env.read_env()` is called correctly in your `settings.py` before attempting to access variables. If an environment variable is set externally and needs to be overridden by the `.env` file, pass `overwrite=True` to `env.read_env()` (e.g., `env.read_env(overwrite=True)`).
ModuleNotFoundError: No module named 'environ'
The `django-environ` package (which provides the `environ` module) is not installed in your active Python environment, or the Python interpreter being used is not the one associated with the environment where `django-environ` is installed.
fixActivate your Python virtual environment if you are using one. Install the `django-environ` package using pip: `pip install django-environ`. Also, check for any local Python files named `environ.py` that might be clashing with the library's import.
KeyError: 'SECRET_KEY'
This `KeyError` occurs when `env('VAR_NAME')` is called, but the environment variable `VAR_NAME` is not found in `os.environ` after `django-environ` attempts to load variables, and no default value has been provided in the `env()` call.
fixEnsure the `.env` file contains an entry for the missing key (e.g., `SECRET_KEY=your_value`). Verify that `environ.Env.read_env()` is called successfully before you attempt to access the variable using `env('SECRET_KEY')`. For non-critical settings, you can provide a default value to prevent the `KeyError` (e.g., `DEBUG = env('DEBUG', default=False)`). Issues with special characters in DATABASE_URL (e.g., '#' in password)
Special characters such as '#' in URL-parsed environment variables like `DATABASE_URL` are often not properly URL-encoded, causing `django-environ`'s underlying URL parser (which uses `urllib` following RFC 3986) to misinterpret the string (e.g., treating '#' as the start of a comment).
fixURL-encode any unsafe characters within the values of your URL-based environment variables in the `.env` file. For instance, replace a pound sign (`#`) in a password with its URL-encoded equivalent (`%23`).
```
# Original (problematic)
DATABASE_URL="postgres://user:pass#word@host:port/dbname"
# Fix (URL-encode '#')
DATABASE_URL="postgres://user:pass%23word@host:port/dbname"
```
Upgrade
Version history
0.14.0latest on PyPI · released Jun 18, 2026
Audit
Dependencies
DjangorequiredCore functionality is built around Django's settings system.