django-environ is the Python package that allows you to use Twelve-factor methodology to configure your Django application with environment variables.
For that, it gives you an easy way to configure Django application using environment variables obtained from an environment file and provided by the OS:
import environ
import os
env = environ.Env(
# set casting, default value
DEBUG=(bool, False)
)
# Set the project base directory
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
# Take environment variables from .env file
environ.Env.read_env(os.path.join(BASE_DIR, '.env'))
# False if not in os.environ because of casting above
DEBUG = env('DEBUG')
# Raises Django's ImproperlyConfigured
# exception if SECRET_KEY not in os.environ
SECRET_KEY = env('SECRET_KEY')
# Parse database connection url strings
# like psql://user:pass@127.0.0.1:8458/db
DATABASES = {
# read os.environ['DATABASE_URL'] and raises
# ImproperlyConfigured exception if not found
#
# The db() method is an alias for db_url().
'default': env.db(),
# read os.environ['SQLITE_URL']
'extra': env.db_url(
'SQLITE_URL',
default='sqlite:////tmp/my-tmp-sqlite.db'
)
}
CACHES = {
# Read os.environ['CACHE_URL'] and raises
# ImproperlyConfigured exception if not found.
#
# The cache() method is an alias for cache_url().
'default': env.cache(),
# read os.environ['REDIS_URL']
'redis': env.cache_url('REDIS_URL')
}The idea of this package is to unify a lot of packages that make the same stuff: Take a string from os.environ, parse and cast it to some of useful python typed variables. To do that and to use the 12factor approach, some connection strings are expressed as url, so this package can parse it and return a urllib.parse.ParseResult. These strings from os.environ are loaded from a .env file and filled in os.environ with setdefault method, to avoid to overwrite the real environ. A similar approach is used in Two Scoops of Django book and explained in 12factor-django article.
Using django-environ you can stop to make a lot of unversioned settings_*.py to configure your app. See cookiecutter-django for a concrete example on using with a django project.
Feature Support
Fast and easy multi environment for deploy
Fill os.environ with .env file variables
Variables casting
Url variables exploded to django specific package settings
Optional support for Docker-style file based config variables (use environ.FileAwareEnv instead of environ.Env)
Project Information
django-environ is released under the MIT / X11 License, its documentation lives at Read the Docs, the code on GitHub, and the latest release on PyPI.
It’s rigorously tested on Python 3.9+, and officially supports Django 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, and 6.0.
If you’d like to contribute to django-environ you’re most welcome!
Support
Should you have any question, any remark, or if you find a bug, or if there is something you can’t do with the django-environ, please open an issue.
Contributing
If you would like to contribute to django-environ, please take a look at the current issues. If there is a bug or feature that you want but it isn’t listed, make an issue and work on it.
Bug reports
Before raising an issue, please ensure that you are using the latest version of django-environ.
Please provide the following information with your issue to enable us to respond as quickly as possible.
The relevant versions of the packages you are using.
The steps to recreate your issue.
The full stacktrace if there is an exception.
An executable code example where possible
Guidelines for bug reports:
Use the GitHub issue search — check if the issue has already been reported.
Check if the issue has been fixed — try to reproduce it using the latest main or develop branch in the repository.
Isolate the problem — create a reduced test case and a live example.
A good bug report shouldn’t leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What OS experience the problem? What would you expect to be the outcome? All these details will help people to fix any potential bugs.
Feature requests
Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It’s up to you to make a strong case to convince the project’s developers of the merits of this feature. Please provide as much detail and context as possible.
Pull requests
Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
Follow this process if you’d like your work considered for inclusion in the project:
Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
Fork the repository on GitHub to start making your changes to the develop branch (or branch off of it).
Write a test which shows that the bug was fixed or that the feature works as expected.
Send a pull request and bug the maintainer until it gets merged and published.
If you are intending to implement a fairly large feature we’d appreciate if you open an issue with GitHub detailing your use case and intended solution to discuss how it might impact other work that is in flight.
We also appreciate it if you take the time to update and write tests for any changes you submit.
By submitting a patch, you agree to allow the project owner to license your work under the same license as that used by the project.
Resources
Release Information
v0.14.0 - 18-June-2026
Added
Changed
Updated Env.read_env() to accept path-like and file-like objects without closing file-like objects supplied by the caller #633.
Fixed
Added an explicit error when Env.read_env() cannot determine its caller frame while resolving the default .env path #633.
Security Policy
Reporting a Vulnerability
If you discover a security vulnerability within django-environ, please send an e-mail to Daniele Faraglia via daniele.faraglia+oss@gmail.com. All security vulnerabilities will be promptly addressed.
Credits
django-environ was initially created by Daniele Faraglia and currently maintained by Serghei Iakovlev.
A full list of contributors can be found in GitHub.
Acknowledgments
The existence of django-environ would have been impossible without these projects:
Release files for django-environ 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| django_environ-0.14.0.tar.gz | 60.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_environ-0.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 81.4 kB
Release files / django_environ-0.14.0.tar.gz
| Download URL | django_environ-0.14.0.tar.gz |
|---|---|
| Size | 60.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6c48d93b9d2ff8a3ea14099e90c35aa4f101c1b4d5f262dfee0d27b06742ed7
|
|
BLAKE2b-256 checksum How to use checksums |
57e14c4ddcf6e90f023e89edb1d92f9a7fffce61ad4b691df497f2f5c0be6e26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / django_environ-0.14.0-py3-none-any.whl
| Download URL | django_environ-0.14.0-py3-none-any.whl |
|---|---|
| Size | 20.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8dbe8a57f0a540ab8abd6f54f230de5e99e3a2c9d797cb9caecb037bca3d47d8
|
|
BLAKE2b-256 checksum How to use checksums |
1afe67b423fc30f16d10259e901320fbc121746bf168aaaad9043e6ebb0110c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
