{"id":"ff0fd41d9c0e8754","repo":"pallets/flask","slug":"python-dotenv-must-be-installed-to-load-an-env-fil","errorCode":null,"errorMessage":"python-dotenv must be installed to load an env file.","messagePattern":"python-dotenv must be installed to load an env file\\.","errorType":"validation","errorClass":"click.BadParameter","httpStatus":null,"severity":"error","filePath":"src/flask/cli.py","lineNumber":502,"sourceCode":"\n_debug_option = click.Option(\n    [\"--debug/--no-debug\"],\n    help=\"Set debug mode.\",\n    expose_value=False,\n    callback=_set_debug,\n)\n\n\ndef _env_file_callback(\n    ctx: click.Context, param: click.Option, value: str | None\n) -> str | None:\n    try:\n        import dotenv  # noqa: F401\n    except ImportError:\n        # Only show an error if a value was passed, otherwise we still want to\n        # call load_dotenv and show a message without exiting.\n        if value is not None:\n            raise click.BadParameter(\n                \"python-dotenv must be installed to load an env file.\",\n                ctx=ctx,\n                param=param,\n            ) from None\n\n    # Load if a value was passed, or we want to load default files, or both.\n    if value is not None or ctx.obj.load_dotenv_defaults:\n        load_dotenv(value, load_defaults=ctx.obj.load_dotenv_defaults)\n\n    return value\n\n\n# This option is eager so env vars are loaded as early as possible to be\n# used by other options.\n_env_file_option = click.Option(\n    [\"-e\", \"--env-file\"],\n    type=click.Path(exists=True, dir_okay=False),\n    help=(","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/pallets/flask/blob/6a2f545bfd8ed31e19066a299296917e034aca58/src/flask/cli.py#L484-L520","documentation":"A click.BadParameter raised by `_env_file_callback` when the user explicitly passes `-e/--env-file` but `import dotenv` fails. Loading env files requires the optional python-dotenv dependency; Flask only errors when a file was explicitly requested — without `-e` it silently skips dotenv loading.","triggerScenarios":"`flask -e .env.local run` (or any command with `--env-file <path>`) in an environment where python-dotenv is not installed.","commonSituations":"Fresh virtualenv or slim Docker image installed with plain `pip install flask` (dotenv is not a hard dependency); dev vs. prod dependency split where python-dotenv sits only in dev requirements; also bites indirectly when .flaskenv files are silently ignored, leading users to add -e explicitly and hit this error.","solutions":["Install the dependency in the active environment: `pip install python-dotenv` (or `pip install 'flask[dotenv]'`).","Add python-dotenv to the requirements/pyproject of every environment that uses --env-file, including Docker images and CI.","Alternatively drop `-e` and export the variables directly in the shell or process manager."],"exampleFix":"# before\nflask -e .env run   # BadParameter: python-dotenv must be installed\n# after\npip install python-dotenv\nflask -e .env run","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec(\"dotenv\") is None:\n    raise SystemExit(\"pip install python-dotenv (or 'flask[dotenv]') to load env files\")","typeGuard":null,"tryCatchPattern":"try:\n    load_dotenv(path)\nexcept UsageError:\n    print(\"python-dotenv missing — install it or drop the --env-file flag\", file=sys.stderr)\n    sys.exit(2)","preventionTips":["Add python-dotenv to project dependencies (pip install 'flask[dotenv]') whenever .env/.flaskenv files exist","Note the error is raised only when --env-file is explicit; implicit .env loading is silently skipped without dotenv — pin the dep so both paths work","Verify the environment loaded via 'flask --app ... shell' rather than assuming"],"tags":["flask","cli","dotenv","dependencies"],"analyzedSha":"6a2f545bfd8ed31e19066a299296917e034aca58","analyzedAt":"2026-07-31T19:13:49.921Z","schemaVersion":2}