load-dotenv

Common errors

• KeyError: 'MY_VAR' or TypeError: 'NoneType' object is not subscriptable

  cause The environment variable `MY_VAR` was not loaded, not present in the `.env` file, or the `.env` file itself was not found/loaded when accessing `os.environ['MY_VAR']` or calling a method on `os.getenv('MY_VAR')` when it returns `None`.
  fix Ensure `load_dotenv()` is called early in your application's entry point. Verify `MY_VAR` exists in your `.env` file and that the file is correctly placed (or specify `dotenv_path`). Use `os.getenv('MY_VAR', 'default_value')` to provide fallbacks and prevent `TypeError`.

• Environment variable not updating / Old value of variable is loaded

  cause `load_dotenv()` by default does not overwrite existing environment variables that were already set in the shell before the script runs.
  fix If you intend to prioritize values from `.env` over existing shell variables, call `load_dotenv(override=True)`.

• '.env file not found' (when expecting variables to load)

  cause The `load_dotenv()` function couldn't locate a `.env` file in the current directory or any parent directories as it searches upwards.
  fix Place your `.env` file in the project's root directory. Alternatively, provide the explicit path to your `.env` file using the `dotenv_path` argument: `load_dotenv(dotenv_path='/path/to/your/.env')`.

Warnings

• gotcha `load_dotenv()` does not overwrite existing environment variables by default.
  Fix: To force `load-dotenv` to overwrite existing shell variables, pass `override=True` to the function: `load_dotenv(override=True)`.
• gotcha The `.env` file location search behavior can be unexpected.
  Fix: `load_dotenv()` searches for the `.env` file upwards from the current working directory. Ensure your `.env` file is in the project root or a parent directory, or explicitly provide the path: `load_dotenv(dotenv_path='/path/to/your/.env')`.
• gotcha Committing `.env` files to version control poses a significant security risk.
  Fix: `.env` files often contain sensitive information (API keys, database credentials). Always add `.env` to your `.gitignore` file. Use environment variables directly in production environments and consider dedicated secrets management systems.
• gotcha Values with quotes or empty values are parsed literally, potentially leading to unexpected results.
  Fix: `KEY="value"` will include the quotes in the loaded string. For standard string values, generally omit quotes (`KEY=value`). `KEY=` will result in an empty string (`''`), not `None`. Handle empty strings explicitly when accessing variables.

Install

• pip install load-dotenv Install latest version

Imports

• load_dotenv
  wrong:

  from dotenv import load_dotenv

  correct:

  from load_dotenv import load_dotenv

  While `load-dotenv` re-exports `python-dotenv`'s function, direct import from 'dotenv' bypasses this wrapper.

Quickstart

Initializes environment variables by calling `load_dotenv()`. This will search for a `.env` file in the current directory and its parents, loading any key-value pairs found into `os.environ`. Access variables using `os.getenv()`.

import os
from load_dotenv import load_dotenv

# Create a dummy .env file for demonstration
# In a real scenario, this file would exist beforehand
with open('.env', 'w') as f:
    f.write('DB_HOST=localhost\n')
    f.write('DB_USER=admin\n')
    f.write('DB_PASSWORD=secret_password\n')

load_dotenv() # take environment variables from .env.

# Access environment variables
db_host = os.getenv("DB_HOST")
db_user = os.getenv("DB_USER")
db_password = os.getenv("DB_PASSWORD")

print(f"DB Host: {db_host}")
print(f"DB User: {db_user}")
print(f"DB Password: {db_password}")

# Clean up the dummy .env file
os.remove('.env')