load_dotenv() — flask Function Reference

Architecture documentation for the load_dotenv() function in cli.py from the flask codebase.

Function python ApplicationCore Scaffolding called by 1

Entity Profile

ApplicationCore→ Scaffolding→ load_dotenv() — flask Function Reference

Dependency Diagram

graph TD
  2566357e_2f99_c4dc_7c83_f5d07e100474["load_dotenv()"]
  a96499c3_f8a9_e782_f156_1c1ee4a86c69["cli.py"]
  2566357e_2f99_c4dc_7c83_f5d07e100474 -->|defined in| a96499c3_f8a9_e782_f156_1c1ee4a86c69
  b69f640f_f9cb_f4cb_3340_949db6a648e8["_env_file_callback()"]
  b69f640f_f9cb_f4cb_3340_949db6a648e8 -->|calls| 2566357e_2f99_c4dc_7c83_f5d07e100474
  style 2566357e_2f99_c4dc_7c83_f5d07e100474 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

src/flask/cli.py lines 698–763

def load_dotenv(
    path: str | os.PathLike[str] | None = None, load_defaults: bool = True
) -> bool:
    """Load "dotenv" files to set environment variables. A given path takes
    precedence over ``.env``, which takes precedence over ``.flaskenv``. After
    loading and combining these files, values are only set if the key is not
    already set in ``os.environ``.

    This is a no-op if `python-dotenv`_ is not installed.

    .. _python-dotenv: https://github.com/theskumar/python-dotenv#readme

    :param path: Load the file at this location.
    :param load_defaults: Search for and load the default ``.flaskenv`` and
        ``.env`` files.
    :return: ``True`` if at least one env var was loaded.

    .. versionchanged:: 3.1
        Added the ``load_defaults`` parameter. A given path takes precedence
        over default files.

    .. versionchanged:: 2.0
        The current directory is not changed to the location of the
        loaded file.

    .. versionchanged:: 2.0
        When loading the env files, set the default encoding to UTF-8.

    .. versionchanged:: 1.1.0
        Returns ``False`` when python-dotenv is not installed, or when
        the given path isn't a file.

    .. versionadded:: 1.0
    """
    try:
        import dotenv
    except ImportError:
        if path or os.path.isfile(".env") or os.path.isfile(".flaskenv"):
            click.secho(
                " * Tip: There are .env files present. Install python-dotenv"
                " to use them.",
                fg="yellow",
                err=True,
            )

        return False

    data: dict[str, str | None] = {}

    if load_defaults:
        for default_name in (".flaskenv", ".env"):
            if not (default_path := dotenv.find_dotenv(default_name, usecwd=True)):
                continue

            data |= dotenv.dotenv_values(default_path, encoding="utf-8")

    if path is not None and os.path.isfile(path):
        data |= dotenv.dotenv_values(path, encoding="utf-8")

    for key, value in data.items():
        if key in os.environ or value is None:
            continue

        os.environ[key] = value

    return bool(data)  # True if at least one env var was loaded.