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

[AhsanSheraz]

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:

Scenario	Current behavior	With strict=True
.env file not found	Returns False silently	Raises FileNotFoundError
Invalid/unparseable line	logger.warning()	Raises ValueError with line number
Everything OK	Returns True	Returns True (unchanged)

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.

strict	verbose	Missing file behavior
False	False	Silent (returns False)
False	True	logger.info() warning
True	False	Raises FileNotFoundError
True	True	Raises FileNotFoundError (no warning logged)

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

[AhsanSheraz]

Hey folks! 👋 This issue and the accompanying PR (#632) implement a strict mode that addresses the silent failure problems many of you have raised over the years. I'd love to hear your thoughts on the approach.

Tagging people who've been involved in related issues/PRs:

• @Qwerty-133 — you opened Raise exceptions when encountering errors in files. #467 requesting exceptions on errors
• @rptaylor — you opened requireFile option for strict checking of env file existence #297 requesting strict file existence checking, and commented on load_dotenv() returns True even if .env file is not found #321
• @scollovati — you opened load_dotenv() returns True even if .env file is not found #321 about load_dotenv() returning True on missing files
• @mtmail — you opened PR File parsing: Option to raise exception instead of warning #520 implementing parse-error exceptions
• @HairlessVillager — you opened Feature Request: Exception or Warning on Duplicate Configuration Items #591 about duplicate config handling
• @bandtank — you opened dotenv_load with bad file path doesn't error #164 about bad file paths not erroring

And others who commented on these issues:
@iamsannyrai @ethsanders @larsks @cbarkinozer @kaskogsholm @reorx @guhcampos @kvfi @drkarthi @srgykuz @mbUSC

TL;DR of the proposal:

# Existing behavior unchanged (strict=False by default)
load_dotenv()

# Opt-in strict mode
load_dotenv(strict=True)
# → FileNotFoundError if .env missing
# → ValueError if any line can't be parsed

100% backwards compatible, opt-in only. The PR is up at #632 — would appreciate your feedback on whether this covers your use cases!