Registry / web-framework / django-dotenv

django-dotenv

library1.4.2pypypi✓ verified 24d ago

django-dotenv is a Python library designed to simplify the loading of environment variables from .env files specifically within Django projects. It aims to make `manage.py` and WSGI applications aware of .env configurations, addressing a common configuration challenge for Django applications. As of its last release, it offers basic .env file parsing functionality.

web-framework auth-security

pip install django-dotenv

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-DOTENV

django-dotenv

web-frameworkpythonv1.4.2

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.2 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.008s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.006s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

read_dotenv

✓ import dotenv; dotenv.read_dotenv()

✗ from dotenv import load_dotenv

The `load_dotenv` function is part of `python-dotenv`, which conflicts with `django-dotenv`.

To integrate django-dotenv, call `dotenv.read_dotenv()` early in your Django project's `manage.py` or `wsgi.py` file. This loads variables from a `.env` file (typically in the project root) into `os.environ`, making them accessible throughout your application.

import os import dotenv # Recommended to call early in manage.py or wsgi.py # For manage.py, place before os.environ.setdefault(...) # For wsgi.py, place before application = get_wsgi_application() dotenv.read_dotenv() # Access environment variables as usual SECRET_KEY = os.environ.get('SECRET_KEY', 'your-fallback-secret-key') DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true' DATABASE_URL = os.environ.get('DATABASE_URL', '') print(f"SECRET_KEY: {SECRET_KEY}") print(f"DEBUG: {DEBUG}") print(f"DATABASE_URL: {DATABASE_URL}")

Debug

Known issues

breakingSupport for Python 2.6 and Python 3.2 was removed in version 1.4.1. Projects still using these Python versions will need to either upgrade their Python environment or pin `django-dotenv` to an earlier version (e.g., `<1.4.1`).

fix

Upgrade to a supported Python version (3.4+), or downgrade `django-dotenv` to a version older than 1.4.1.

affects: >=1.4.1

gotchaA common `AttributeError: module 'dotenv' has no attribute 'read_dotenv'` occurs if `python-dotenv` is installed alongside `django-dotenv`. The `dotenv` module provided by `python-dotenv` can shadow the `django-dotenv`'s module, causing the `read_dotenv` function to be unavailable.

fix

If using `django-dotenv`, ensure `python-dotenv` is *not* installed in the same environment. Uninstall `python-dotenv` to resolve the conflict (`pip uninstall python-dotenv`). If `python-dotenv` functionality is preferred, migrate to using `python-dotenv` instead, which is generally more actively maintained.

affects: All

gotchaBy default, environment variables already defined in the shell take precedence over those specified in the `.env` file. This means shell variables will not be overridden by the `.env` file's contents unless explicitly instructed.

fix

To force the `.env` file's variables to override existing shell environment variables, call `dotenv.read_dotenv(override=True)`.

affects: All

gotchaThe `django-dotenv` library has not been actively maintained since its last release (v1.4.2) in December 2017. For new projects or more robust and actively maintained `.env` handling, the `python-dotenv` library is generally recommended as a more universal solution, even for Django applications, due to its ongoing development and broader feature set.

fix

Consider migrating to `python-dotenv` (`pip install python-dotenv`) and using `from dotenv import load_dotenv; load_dotenv()` instead, along with `os.getenv()` or similar mechanisms for accessing variables.

affects: All

Errors

Common errors & fixes

AttributeError: module 'dotenv' has no attribute 'read_dotenv'

This error occurs because both `django-dotenv` and `python-dotenv` packages are installed, and `python-dotenv`'s `dotenv` module is shadowing `django-dotenv`'s `dotenv` module, which contains the `read_dotenv` function.

fix

Uninstall `python-dotenv` to resolve the conflict, as `django-dotenv` provides its own `dotenv` module. `pip uninstall python-dotenv`

ModuleNotFoundError: No module named 'dotenv'

This error typically means that the `django-dotenv` package (or `python-dotenv`, if that was intended) is not installed in the current Python environment, or there's a typo in the import statement.

fix

Ensure `django-dotenv` is installed: `pip install django-dotenv`. If attempting to use `python-dotenv` (a more actively maintained alternative), install it with `pip install python-dotenv` and import it using `from dotenv import load_dotenv`.

Environment variables from .env file are not loaded or do not override existing shell variables.

By default, `django-dotenv` (and `python-dotenv`) respects environment variables already defined in the shell, meaning they take precedence over those in the `.env` file.

fix

To force the `.env` file's variables to override existing shell environment variables, call `dotenv.read_dotenv(override=True)` or `load_dotenv(override=True)` if using `python-dotenv`.

django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty. (or similar for other Django settings)

This is a symptom that the `.env` file containing critical Django settings (like `SECRET_KEY`, `DEBUG`, etc.) was not loaded by `django-dotenv` before Django's `settings.py` attempted to access these variables via `os.getenv()`. This could be due to incorrect placement of the `dotenv.read_dotenv()` call or the `.env` file itself.

fix

Ensure `dotenv.read_dotenv()` is called very early in your Django project's startup, typically in `manage.py` and `wsgi.py`. For `manage.py`: `import dotenv; dotenv.read_dotenv()`. For `wsgi.py`: `import os, dotenv; dotenv.read_dotenv(os.path.join(os.path.dirname(os.path.dirname(__file__)), '.env'))`. Also, ensure the `.env` file is in the root of your project (next to `manage.py`).

Upgrade

Version history

1.4.2latest on PyPI · released Dec 11, 2017

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/jpadilla/django-dotenv ↗

packagehttps://pypi.org/project/django-dotenv/ ↗