Skip to content

Comparisons

environ

The Python standard library os module offers operating system utilities, including os.environ for working with environment variables. os.environ only handles strings, and doesn't include tools for file I/O.

os.environ is instantiated from os._Environ, which is an implementation of collections.abc.MutableMapping. The source code for os.environ can be found in python/cpython/Lib/os.py, and the source code for collections.abc.MutableMapping can be found in python/cpython/Lib/_collections_abc.py. As explained in the docstring for MutableMapping:

A MutableMapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __setitem__, __delitem__, __iter__, and __len__.

Subclasses of collections.abc.MutableMapping, such as os._Environ, need to provide implementations of each of those methods.

Type stubs for os.environ are in python/typeshed/stdlib/os/__init__.pyi. Stubs for collections.abc.MutableMapping are in python/typeshed/stdlib/typing.pyi (these are the type stubs for the standard library typing module, which aliases collections.abc.MutableMapping).

See the os module docs and the docs on mapping types for more information.

environs

  • environs is a project with useful features for managing .env files and application settings. Its API was inspired by django-environ and envparse (and the maintainers considered merging environs and envparse into one project). The README compares environs to os.environ, and justifies the additional features that environs provides.
  • While it separates config from code, as suggested by the twelve-factor app methodology, it also combines environment variables and settings. Environment variables and their type-casted setting counterparts are combined into the same model.
  • Initially, the source code wasn't consistently type-annotated (sloria/environs#186), but based on its PEP 561 marker file, it appears to be type-annotated now.
  • Depends on python-dotenv (sloria/environs#196), so it inherits the limitations described in the python-dotenv section.

Pydantic

Settings configuration

Pydantic 2 provides settings management through the separate pydantic-settings package. Its BaseSettings model reads typed settings from environment variables and other sources, then uses Pydantic for validation.

The fastenv Pydantic integration offers a similar API as pydantic-settings, but with fastenv replacing python-dotenv. The differences from pydantic-settings are described below.

Simple Pydantic settings model

import os

from fastenv import BaseSettings

os.environ["BOOLEAN_SETTING"] = "false"
os.environ["INTEGER_SETTING"] = "123"
os.environ["STRING_SETTING"] = "example_value"


class SimpleSettings(BaseSettings):
    boolean_setting: bool = True
    integer_setting: int = 000
    string_setting: str = "default_value"


print(SimpleSettings().model_dump())
# {"boolean_setting": False, "integer_setting": 123, "string_setting": "example_value"}

File I/O

  • fastenv adds await Settings.load() to read built-in file sources asynchronously through AnyIO before validation. The synchronous Settings(...) constructor remains available for compatibility with pydantic-settings.
  • pydantic-settings loads dotenv files with python-dotenv. The fastenv integration uses its own parser instead and leaves the process environment unchanged.
  • Both settings implementations ignore missing dotenv files. Fields without defaults still require a value from another source. By comparison, fastenv.load_dotenv raises FileNotFoundError by default.

Command-line interfaces

Pydantic Settings includes command-line support because CLI arguments can be another source of application settings. Its documentation identifies two use cases:

  1. Override fields in Pydantic models with command-line arguments.
  2. Define command-line applications using Pydantic models.

The first use case lets an application reuse its settings model's fields, types, and descriptions to generate options and help text. For example, --database.host localhost can override one field while a configuration file and environment variables provide the remaining database settings. The inputs are combined before model validation, so a required field need not come from the command line if another source supplies it. Avoiding duplicate model declarations and validating merged partial inputs were explicit motivations in the original discussion.

The implementation developed through several proposals:

Click offers another way to build CLI applications. In April 2025, pydantic/pydantic-settings#584 proposed generating Click options and arguments from settings models and passing model instances to command functions. A maintainer declined the integration, citing uncertain added value and the implementation and maintenance work, while leaving open reconsideration if more users wanted it. This decision concerned automatic integration. Applications can still combine their own Click commands with Pydantic settings models.

fastenv keeps its integration focused on loading and validating settings. Generating parsers and executing commands would add a separate CLI API to maintain. Applications can use Click or Python's standard-library argparse, then pass explicitly supplied options to Settings(**overrides) or a custom source. Omitting unspecified options preserves environment and file values. The tradeoff is that fastenv does not generate a CLI from the model or provide Pydantic Settings' CLI APIs.

Differences from pydantic-settings

fastenv intentionally differs from pydantic-settings in these areas:

  • Imports and dependencies. Import settings APIs from fastenv and install fastenv[settings] for Pydantic support. This extra does not depend on pydantic-settings or python-dotenv.
  • Command-line interfaces. fastenv does not expose pydantic-settings CLI APIs such as CliApp, CliSettingsSource, CLI annotations, or cli_* configuration and _cli_* constructor options. See the CLI comparison for the use cases, implementation history, and rationale for keeping argument parsing in applications.
  • YAML configuration. fastenv does not support YAML settings files or provide YamlConfigSettingsSource, the yaml_file, yaml_file_encoding, or yaml_config_section options, or a YAML dependency extra. This avoids installing a separate YAML parser. Use dotenv, JSON, or TOML files instead. JSON and TOML parsing use Python's standard library.
  • Dotenv syntax. Files use fastenv's parser, including shell tokenization, whitespace-separated assignments, and literal variable references such as ${HOME}. There is no variable interpolation. Bare names without = are ignored, and invalid shell quoting raises an error. Whitespace and quote handling can differ from python-dotenv.
  • Cloud secret services. pydantic-settings supports AWS Secrets Manager, AWS Systems Manager Parameter Store, Azure Key Vault, and Google Cloud Secret Manager. fastenv does not provide these integrations or their SDK dependencies. AWSSecretsManagerSettingsSource, AzureKeyVaultSettingsSource, GoogleSecretManagerSettingsSource, and SecretVersion are intentionally absent from fastenv.
  • Cloud object storage. fastenv[cloud] provides its own asynchronous client for dotenv files in S3-compatible object storage, including AWS S3, Backblaze B2, and Cloudflare R2. It avoids Boto3. Download a dotenv file before loading its path with Settings(_env_file=...). Object storage support does not include SSM Parameter Store or cloud secret services.
  • Compatibility scope. The reference release is pydantic-settings 2.15.0 for environment variables, local files, secret directories, and custom sources. Private methods, module paths, and exact error messages are outside the compatibility contract. fastenv.__version__ reports the fastenv version. Behavioral probes check the supported API without requiring every upstream export.

python-decouple

  • python-decouple loads settings from .env and .ini files. Its supported configuration file format appears to be inspired by Foreman, a Ruby configuration management tool.
  • Variables are set with calls to instances of its AutoConfig class, which offers type-casting to convert strings to other Python types: config("DEBUG", cast=bool).
  • Source code is not type-annotated.
  • Classes inherit from object, and therefore require their own implementations of methods already present in other data structures. This could be easily eliminated by inheriting from a mapping data structure such as collections.abc.MutableMapping.
  • Continues supporting Python 2 after its end-of-life, and has not been tested on the latest versions of Python 3.

python-dotenv

python-dotenv is a package for loading .env files and setting environment variables. It was started by Django co-creator Jacob Kaplan-Moss in 2013, and was originally called django-dotenv. It is used by Uvicorn and pydantic, and suggested in the FastAPI docs.

Environment variables

  • Its primary data structure, dotenv.main.DotEnv, inherits from object. As a result, it requires its own mapping methods (such as dict()) that could be obviated by inheriting from a mapping data structure such as collections.abc.MutableMapping.
  • Other methods have confusing, counter-intuitive APIs. For example, the load_dotenv() function is supposed to "Parse a .env file and then load all the variables found as environment variables," according to its docstring. However, the function always returns True, even if no .env file is found or no environment variables are set, because of DotEnv.set_as_environment_variables(). Furthermore, this confusing behavior is not documented, because, as the maintainer commented, "The return value of load_dotenv is undocumented as I was planning to do something useful with it, but could not settle down to one."

File I/O

  • Loads files with the synchronous open() built-in function. Async support is not provided.
  • Does not integrate with object storage like AWS S3.

Project maintenance

Comparing fastenv and python-dotenv

DotEnv

  • Both fastenv and python-dotenv provide a DotEnv class for managing environment variables
  • fastenv.DotEnv inherits from collections.abc.MutableMapping, dotenv.main.DotEnv inherits from object
  • fastenv includes DotEnv in its __all__, python-dotenv does not (it must be directly imported from dotenv.main)

find_dotenv

  • fastenv: await fastenv.find_dotenv() (async)
  • python-dotenv: dotenv.find_dotenv() (sync)
  • Both fastenv and python-dotenv look for ".env" by default
  • Both python-dotenv and fastenv return os.PathLike objects
  • fastenv raises FileNotFoundError exceptions by default if files are not found, python-dotenv does not

load_dotenv

  • fastenv: await fastenv.load_dotenv() (async)
  • python-dotenv: dotenv.load_dotenv() (sync)
  • fastenv.load_dotenv can load multiple .env files in a single call, dotenv.load_dotenv cannot
  • fastenv.load_dotenv logs the number of environment variables loaded, dotenv.load_dotenv does not
  • fastenv.load_dotenv returns a DotEnv model, dotenv.load_dotenv returns True (even if no .env file was found and no environment variables were loaded)

find_dotenv with load_dotenv

Users who would like to ensure their .env files are found, and log the result, should be aware that dotenv.load_dotenv:

  • Only calls find_dotenv if a file path is not provided, and does not pass an argument through to find_dotenv to raise exceptions if the file is not found
  • Requires a call to DotEnv.set_as_environment_variables to actually set environment variables
  • Does not provide logging
  • Does not provide exception handling (its verbose argument does not necessarily raise an exception)
  • Does not return the DotEnv instance created by load_dotenv, but always returns True, even if no .env file is found or no environment variables are set

Something like the following is therefore needed instead of using dotenv.load_dotenv:

Finding and loading a .env file with python-dotenv

import logging

from dotenv import find_dotenv
from dotenv.main import DotEnv


def find_and_load_my_dotenv(env_file: str = ".env") -> DotEnv:
    try:
        logger = logging.getLogger()
        source = find_dotenv(filename=env_file, raise_error_if_not_found=True)
        dotenv = DotEnv(source, verbose=True)
        dotenv.set_as_environment_variables()
        logger.info(
            f"Python-dotenv loaded {len(dotenv.dict())} variables from {env_file}"
        )
        return dotenv
    except Exception as e:
        logger.error(f"Error loading {env_file}: {e.__class__.__qualname__} {e}")
        raise

The above effect can be accomplished with fastenv in a single call, await fastenv.load_dotenv(find_source=True). This call to fastenv.load_dotenv:

  • Finds the .env file (find_source=True) with its find_dotenv method and the file name provided (".env" by default), logging and raising a FileNotFoundError if not found
  • Sets environment variables automatically
  • Logs successes and errors automatically
  • Raises exceptions by default
  • Returns a DotEnv instance

dotenv_values

  • fastenv: await fastenv.dotenv_values() (async)
  • python-dotenv: dotenv.dotenv_values() (sync)
  • fastenv.dotenv_values offers a find_dotenv argument to find files before loading and returning values, dotenv.dotenv_values does not
  • fastenv.dotenv_values offers a raise_exceptions argument to determine whether or not exceptions will be raised, dotenv.dotenv_values does not (its verbose argument does not necessarily raise an exception)
  • fastenv.dotenv_values logs successes and errors automatically, dotenv.dotenv_values does not

Writing to .env files

  • fastenv: await fastenv.dump_dotenv() (async, and writes an entire DotEnv model to a file)
  • python-dotenv: dotenv.get_key(), dotenv.set_key(), dotenv.unset_key() (sync, and can only write single variables to a file)

Starlette

Settings configuration

Starlette offers a config module for working with environment variables and settings, which takes inspiration from python-decouple. Settings are created by calling a Starlette Config instance.

Example

import starlette.config

config = starlette.config.Config()
config("FOO_VARIABLE", cast=str, default="baz")

Starlette will look for an environment variable FOO_VARIABLE. For example, setting FOO_VARIABLE=bar in the environment makes this lookup return "bar". If the environment variable is unset, the lookup returns "baz". The cast keyword argument allows use of Starlette type-casting.

Type-casting

Type-casting provides improvements over some aspects of the standard library. For example, Starlette intuitively casts Boolean values, unlike the Python built-in bool type:

Type-casting with starlette.config

.venv ❯ python
bool("false")
# True
import starlette.config

config = starlette.config.Config()
config("BOOLEAN_SETTING", cast=bool, default="false")
# False

One-way configuration preference

Starlette has an opinionated one-way configuration preference (environment variables -> Starlette Config instance). To avoid modifying environment variables after they have been loaded into a Starlette Config instance, Starlette provides its own mapping onto os.environ (starlette.config.environ), which will raise an exception on attempts to change an environment variable that has already been loaded into a corresponding setting on a Config instance.

This protection only applies to starlette.config.environ. Updates to os.environ bypass the protection, and future calls to the Config instance may then read updated values from os.environ depending on config precedence.

While it is useful to have starlette.config.environ synchronized with os.environ, the downside is that starlette.config.environ contains local environment variables loaded from os.environ, and therefore wouldn't typically be dumped to a file.

Environment variables with starlette.config

.venv ❯ python
import os
import starlette.config

os.environ.get("FOO_VARIABLE")
starlette.config.environ["FOO_VARIABLE"] = "bar"
os.environ.get("FOO_VARIABLE")
# 'bar'
config = starlette.config.Config()
config("FOO_VARIABLE", cast=str, default="baz")
# 'bar'
starlette.config.environ["FOO_VARIABLE"] = "foo"
# Traceback (most recent call last):
# File ".venv/lib/python/site-packages/starlette/config.py", line 26, in __setitem__
#     raise EnvironError(
# starlette.config.EnvironError: Attempting to set environ['FOO_VARIABLE'],
# but the value has already been read.
os.environ["FOO_VARIABLE"] = "foo"
os.environ["FOO_VARIABLE"]
# 'foo'
starlette.config.environ["FOO_VARIABLE"]
# 'foo'
config("FOO_VARIABLE", cast=str, default="baz")
# 'foo'

File I/O

  • Starlette Config accepts an env_file keyword argument, which should point to a .env file on disk. It loads the file with the synchronous open() built-in function.
  • If no .env file is found at the path provided by Config(env_file), Starlette will raise a warning instead of a FileNotFoundError (encode/starlette#2422, encode/starlette#2446, encode/starlette#2485). This can lead to issues if applications depend on environment variables that Starlette fails to load.
  • Starlette Config does not support multiple .env files (encode/starlette#432).

Comparing fastenv and Starlette

Install fastenv[starlette] to use fastenv.StarletteConfig, a subclass of Starlette's Config. It preserves Starlette's settings lookup, type casting, defaults, and environment prefixes while adding synchronous and asynchronous loading of multiple dotenv files and TOML settings.

  • Both classes prefer existing environment variables over file values and leave the environment unchanged when loading files.
  • fastenv.StarletteConfig accepts a list or tuple of dotenv paths, with later files overriding earlier files.
  • fastenv.StarletteConfig can load a TOML table as a fallback beneath environment variables and dotenv files, preserving native TOML values.
  • fastenv.StarletteConfig logs file errors and raises them by default. Set raise_exceptions=False to skip failed sources and retain successfully loaded sources.
  • Pass files to fastenv.StarletteConfig(...) in synchronous code, or use await fastenv.StarletteConfig.load(...) inside an existing event loop. Both use the same AnyIO file reader and return an instance with synchronous settings lookups.
  • Without file arguments, fastenv.StarletteConfig() reads settings from the environment and performs no file I/O.

The future of starlette.config

From encode/starlette#432:

I guess we may actually end up pulling the configuration stuff out into a strictly separate package (or indeed even just pointing at python-decouple - since it's the same style).

With 12-factor config you really should have a fairly small set of environment. (Eg. the database configuration should just be a single URL.)

What we will want to do though is provide really good examples of how to arrange things sensibly, so that eg. you have a project that has a settings.py that includes a whole bunch of project configuration, and which you can arrange into separate bits, and demonstrate clearly how the environment should be a small set of variables, but the project settings may be more comprehensive.

We could perfectly well also point to other configuration-management packages that're out there as alternatives.

Other

  • dotenvy can load .env files and apply a type schema to the variables. It does not appear to be actively maintained.
  • env does not add much beyond os.environ (does not even load files), has not been released since 2012, and does not appear to be actively maintained.
  • envparse offers features for parsing and type-casting environment variables, but does not appear to be actively maintained.
  • python-configurator depends on python-dotenv and appears to emphasize TOML settings files.