{"id":5612,"library":"django-dotenv","title":"Django Dotenv","description":"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.","status":"maintenance","version":"1.4.2","language":"python","source_language":"en","source_url":"https://github.com/jpadilla/django-dotenv","tags":["django","environment variables","dotenv","configuration","secrets"],"install":[{"cmd":"pip install django-dotenv","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The `load_dotenv` function is part of `python-dotenv`, which conflicts with `django-dotenv`.","wrong":"from dotenv import load_dotenv","symbol":"read_dotenv","correct":"import dotenv; dotenv.read_dotenv()"}],"quickstart":{"code":"import os\nimport dotenv\n\n# Recommended to call early in manage.py or wsgi.py\n# For manage.py, place before os.environ.setdefault(...)\n# For wsgi.py, place before application = get_wsgi_application()\ndotenv.read_dotenv()\n\n# Access environment variables as usual\nSECRET_KEY = os.environ.get('SECRET_KEY', 'your-fallback-secret-key')\nDEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'\nDATABASE_URL = os.environ.get('DATABASE_URL', '')\n\nprint(f\"SECRET_KEY: {SECRET_KEY}\")\nprint(f\"DEBUG: {DEBUG}\")\nprint(f\"DATABASE_URL: {DATABASE_URL}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to a supported Python version (3.4+), or downgrade `django-dotenv` to a version older than 1.4.1.","message":"Support 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`).","severity":"breaking","affected_versions":">=1.4.1"},{"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.","message":"A 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.","severity":"gotcha","affected_versions":"All"},{"fix":"To force the `.env` file's variables to override existing shell environment variables, call `dotenv.read_dotenv(override=True)`.","message":"By 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'address':37 'aim':26 'applic':32,44 'awar':33 'basic':52 'challeng':41 'common':39 'configur':36,40,61 'design':10 'django':1,4,23,43,57 'django-dotenv':3 'dotenv':2,5,60 'env':19,35,53 'environ':16,58 'file':20,54 'function':56 'last':48 'librari':9 'load':14 'make':28 'manage.py':29 'offer':51 'pars':55 'project':24 'python':8 'releas':49 'secret':62 'simplifi':12 'specif':21 'variabl':17,59 'within':22 'wsgi':31","created_at":"2026-04-14T03:36:11.396153+00:00","updated_at":"2026-04-16T14:30:07.224070+00:00","problems":[{"fix":"Uninstall `python-dotenv` to resolve the conflict, as `django-dotenv` provides its own `dotenv` module. `pip uninstall python-dotenv`","cause":"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.","error":"AttributeError: module 'dotenv' has no attribute 'read_dotenv'"},{"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`.","cause":"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.","error":"ModuleNotFoundError: No module named 'dotenv'"},{"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`.","cause":"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.","error":"Environment variables from .env file are not loaded or do not override existing shell variables."},{"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`).","cause":"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.","error":"django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty. (or similar for other Django settings)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/jpadilla/django-dotenv","docs":null,"changelog":null,"pypi":"https://pypi.org/project/django-dotenv/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}