pallets/flask · error · click.BadParameter

python-dotenv must be installed to load an env file.

Error message

python-dotenv must be installed to load an env file.

What it means

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.

Source

Thrown at src/flask/cli.py:502

_debug_option = click.Option(
    ["--debug/--no-debug"],
    help="Set debug mode.",
    expose_value=False,
    callback=_set_debug,
)


def _env_file_callback(
    ctx: click.Context, param: click.Option, value: str | None
) -> str | None:
    try:
        import dotenv  # noqa: F401
    except ImportError:
        # Only show an error if a value was passed, otherwise we still want to
        # call load_dotenv and show a message without exiting.
        if value is not None:
            raise click.BadParameter(
                "python-dotenv must be installed to load an env file.",
                ctx=ctx,
                param=param,
            ) from None

    # Load if a value was passed, or we want to load default files, or both.
    if value is not None or ctx.obj.load_dotenv_defaults:
        load_dotenv(value, load_defaults=ctx.obj.load_dotenv_defaults)

    return value


# This option is eager so env vars are loaded as early as possible to be
# used by other options.
_env_file_option = click.Option(
    ["-e", "--env-file"],
    type=click.Path(exists=True, dir_okay=False),
    help=(

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Install the dependency in the active environment: `pip install python-dotenv` (or `pip install 'flask[dotenv]'`).
2. Add python-dotenv to the requirements/pyproject of every environment that uses --env-file, including Docker images and CI.
3. Alternatively drop `-e` and export the variables directly in the shell or process manager.

Example fix

# before
flask -e .env run   # BadParameter: python-dotenv must be installed
# after
pip install python-dotenv
flask -e .env run

import importlib.util
if importlib.util.find_spec("dotenv") is None:
    raise SystemExit("pip install python-dotenv (or 'flask[dotenv]') to load env files")

try:
    load_dotenv(path)
except UsageError:
    print("python-dotenv missing — install it or drop the --env-file flag", file=sys.stderr)
    sys.exit(2)

When it happens

Trigger: `flask -e .env.local run` (or any command with `--env-file <path>`) in an environment where python-dotenv is not installed.

Common situations: 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.

Related errors

• While importing {module_name!r}, an ImportError was raised:
• Using ad-hoc certificates requires the cryptography library.
• Install Flask with the 'async' extra in order to use async v
• Detected multiple Flask applications in module '{module.__na
• Detected factory '{attr_name}' in module '{module.__name__}'

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/ff0fd41d9c0e8754.json. Report an issue: GitHub ↗.