Add strict parameter to load_dotenv() and dotenv_values() for fail-fast behavior #631

Problem

python-dotenv currently fails silently in two critical scenarios:

1. Missing .env file — no error raised

load_dotenv("/wrong/path/.env")  # Returns False silently
# App continues with no config — production incident waiting to happen

While PR #388 improved this to return False (previously returned True), almost no one checks the return value. The common pattern is just load_dotenv() at the top of a module.

2. Invalid lines — silently logged as warnings

# .env file contains a typo (colon instead of equals):
# DATABASE_URL: postgres://localhost/db
load_dotenv()  # DATABASE_URL is silently missing
# App falls back to a default or crashes later with a confusing error

As described in PR #520: "I dealt with an .env file that accidentally contained an unparsable line. The software then set a default value and I almost wrote to a wrong database."

Community Demand

This is one of the most requested features, spanning multiple years:

• Raise exceptions when encountering errors in files. #467 — "Raise exceptions when encountering errors in files" (open, 2023)
• requireFile option for strict checking of env file existence #297 — "requireFile option for strict checking of env file existence" (closed without implementation)
• load_dotenv() returns True even if .env file is not found #321 — "load_dotenv() returns True even if .env file is not found" (partially fixed by feat: return False when we do not discover any environment variables #388)
• File parsing: Option to raise exception instead of warning #520 — Open PR implementing parse-error exceptions (not yet merged)
• Feature Request: Exception or Warning on Duplicate Configuration Items #591 — "Exception or Warning on Duplicate Configuration Items" (open, 2025)
• dotenv_load with bad file path doesn't error #164 — "dotenv_load with bad file path doesn't error" (2019)

The DEV Community article "Why load_dotenv() Is an Anti-Pattern" (2025) specifically calls out silent failures as the primary reason developers migrate away from python-dotenv to alternatives like pydantic-settings.

Proposal

Add a strict parameter (default False) to load_dotenv() and dotenv_values():

# Existing behavior preserved (strict=False by default)
load_dotenv()  # silent on missing file or parse errors

# Opt-in strict mode
load_dotenv(strict=True)  # raises on missing file or parse errors

Behavior with strict=True:

Interaction with verbose

strict takes precedence over verbose. When both are True, the exception is raised without emitting a warning first — logging the same message before raising would be an anti-pattern (the exception already carries the information). When strict=False, verbose continues to work as before.

Design Philosophy — Parser Correctness, Not Config Validation

This proposal intentionally stays within python-dotenv's existing philosophy of "populate what is available, let consuming code validate requirements." strict mode does not validate whether specific keys exist, whether values are the correct type, or whether the configuration is "complete" — that is the domain of tools like pydantic-settings.

What strict does is make python-dotenv honest about its own job: "did the file I was asked to read exist?" and "could I parse every line in it?" These are parser-level guarantees, not application-level config validation. The library should be able to tell you when it failed to do what you asked, rather than silently pretending everything is fine.

Backwards Compatibility

• 100% backwards compatible — defaults to False, no behavior change for existing users
• Opt-in only — users must explicitly pass strict=True

Scope

This addresses the umbrella of issues (#467, #297, #520, #591) with a single, clean API addition. The implementation touches main.py only (~20-30 lines), plus tests.

Related: #467, #297, #321, #520, #591, #164