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 synchronousSettings(...)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_dotenvraisesFileNotFoundErrorby 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:
- Override fields in Pydantic models with command-line arguments.
- 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:
- 2019-2020. pydantic/pydantic#756 proposed lightweight argument parsing using familiar Pydantic models. Its author closed the proposal in January 2020 after finding that Typer covered most practical CLI needs, suggesting Pydantic integration there instead.
- January-June 2024. pydantic/pydantic-settings#209 proposed completing the set of settings inputs with files, environment variables, and CLI arguments. Maintainers favored a separate settings source, disabled by default, with named options as an initial scope. PR #214, merged in June 2024, added
CliSettingsSource, including nested fields, collections, generated help, positional arguments, and subcommands. - September 2024. PR #389 added
CliAppto run application commands. During review, a maintainer raised concerns about the amount of CLI code and future maintenance. The author pointed to user requests and proposed limiting further feature growth.
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
fastenvand installfastenv[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, orcli_*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, theyaml_file,yaml_file_encoding, oryaml_config_sectionoptions, 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, andSecretVersionare 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 withSettings(_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
AutoConfigclass, 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 ascollections.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 fromobject. As a result, it requires its own mapping methods (such asdict()) that could be obviated by inheriting from a mapping data structure such ascollections.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 returnsTrue, even if no .env file is found or no environment variables are set, because ofDotEnv.set_as_environment_variables(). Furthermore, this confusing behavior is not documented, because, as the maintainer commented, "The return value ofload_dotenvis 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¶
- Continued supporting Python 2 after its end-of-life (until 0.19.0), so it had to use Python 2 type comments and other legacy cruft.
- Maintainers have not been receptive to improvements (see theskumar/python-dotenv#263 for context).
Comparing fastenv and python-dotenv¶
DotEnv¶
- Both fastenv and python-dotenv provide a
DotEnvclass for managing environment variables fastenv.DotEnvinherits fromcollections.abc.MutableMapping,dotenv.main.DotEnvinherits fromobject- fastenv includes
DotEnvin its__all__, python-dotenv does not (it must be directly imported fromdotenv.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.PathLikeobjects - fastenv raises
FileNotFoundErrorexceptions 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_dotenvcan load multiple .env files in a single call,dotenv.load_dotenvcannotfastenv.load_dotenvlogs the number of environment variables loaded,dotenv.load_dotenvdoes notfastenv.load_dotenvreturns aDotEnvmodel,dotenv.load_dotenvreturnsTrue(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_dotenvif a file path is not provided, and does not pass an argument through tofind_dotenvto raise exceptions if the file is not found - Requires a call to
DotEnv.set_as_environment_variablesto actually set environment variables - Does not provide logging
- Does not provide exception handling (its
verboseargument does not necessarily raise an exception) - Does not return the
DotEnvinstance created byload_dotenv, but always returnsTrue, 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 itsfind_dotenvmethod and the file name provided (".env"by default), logging and raising aFileNotFoundErrorif not found - Sets environment variables automatically
- Logs successes and errors automatically
- Raises exceptions by default
- Returns a
DotEnvinstance
dotenv_values¶
- fastenv:
await fastenv.dotenv_values()(async) - python-dotenv:
dotenv.dotenv_values()(sync) fastenv.dotenv_valuesoffers afind_dotenvargument to find files before loading and returning values,dotenv.dotenv_valuesdoes notfastenv.dotenv_valuesoffers araise_exceptionsargument to determine whether or not exceptions will be raised,dotenv.dotenv_valuesdoes not (itsverboseargument does not necessarily raise an exception)fastenv.dotenv_valueslogs successes and errors automatically,dotenv.dotenv_valuesdoes not
Writing to .env files¶
- fastenv:
await fastenv.dump_dotenv()(async, and writes an entireDotEnvmodel 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
Configaccepts anenv_filekeyword argument, which should point to a .env file on disk. It loads the file with the synchronousopen()built-in function. - If no .env file is found at the path provided by
Config(env_file), Starlette will raise a warning instead of aFileNotFoundError(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
Configdoes 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.StarletteConfigaccepts a list or tuple of dotenv paths, with later files overriding earlier files.fastenv.StarletteConfigcan load a TOML table as a fallback beneath environment variables and dotenv files, preserving native TOML values.fastenv.StarletteConfiglogs file errors and raises them by default. Setraise_exceptions=Falseto skip failed sources and retain successfully loaded sources.- Pass files to
fastenv.StarletteConfig(...)in synchronous code, or useawait 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.pythat 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.