Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#631 コメント 3 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
68/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
静か
技術スタック
python
領域
tooling

調査の方向性

Start by reading main.py, focusing on load_dotenv() and dotenv_values(), then inspect the existing tests for missing files, parse warnings, and verbose behavior. Add coverage for strict=True and the strict/verbose combinations described in the issue; done means missing files and invalid lines raise the specified exceptions while default behavior remains unchanged.

索引モデルが issue の本文から書いたものです。

説明

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:

  • #467 — "Raise exceptions when encountering errors in files" (open, 2023)
  • #297 — "requireFile option for strict checking of env file existence" (closed without implementation)
  • #321 — "load_dotenv() returns True even if .env file is not found" (partially fixed by #388)
  • #520 — Open PR implementing parse-error exceptions (not yet merged)
  • #591 — "Exception or Warning on Duplicate Configuration Items" (open, 2025)
  • #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

主要言語
Python
スター
8.9k
フォーク
585
平均マージ
8日 8時間
マージ済み PR（30日）
5

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

theskumar/python-dotenv のほかの issue

theskumar/python-dotenv の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。