environs

What it is and what it does

environs is a Python library that reads environment variables and casts them to typed Python objects—integers, booleans, dates, lists, dictionaries, and other types—with optional validation. It follows the Twelve-Factor App methodology by keeping configuration separate from code. The library can load variables from .env files without modifying os.environ, and supports prefixing, variable expansion, and custom validation rules.

You use it by instantiating an Env object, optionally calling read_env() to load a .env file, then calling type-specific methods like env.int(), env.bool(), or env.list() to retrieve and cast individual variables. It integrates with marshmallow for validation, allowing you to apply built-in validators or define custom ones. The library is framework-agnostic but has documented patterns for Flask and Django.

Use it for:

• Load database credentials and connection settings from environment variables in production deployments.
• Parse feature flags and debug settings from .env files during local development without hardcoding them.
• Validate and type-cast configuration like port numbers, timeouts, and log levels from environment variables.
• Read Docker secrets or Kubernetes ConfigMaps as environment variables with automatic type conversion.
• Build configuration management that respects the Twelve-Factor App pattern across development, staging, and production.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

environs parses environment variables into typed Python objects with validation, supporting common types like integers, booleans, dates, and collections, while optionally loading from .env files without mutating os.environ.

Yes. environs is actively maintained, has no known vulnerabilities, low install friction, and solves a common problem—parsing and validating environment variables—with a clean API. The permissive MIT license and broad Python version support (3.10+) make it a safe, practical choice for any project that needs configuration management.

Install

environs on PyPI

pip install environs

uv add environs

poetry add environs

Installing environs

Before you install

Low install friction with three lightweight runtime dependencies (python-dotenv, marshmallow, typing-extensions). The package is actively maintained with recent releases and a stable repository.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Quickstart

pip install environs

from environs import env

env.read_env()  # load .env file if present
max_connections = env.int("MAX_CONNECTIONS", default=10)
enable_debug = env.bool("DEBUG", default=False)
repos = env.list("REPOS", default=[])

Requires Python 3.10 or later.

Verify before relying

• Performance characteristics when parsing large numbers of environment variables.
• Compatibility with async frameworks or concurrent environment variable access patterns.

Package facts

Evidence: environs-15.1.0-py3-none-any.whl

Tags

More Software Development packages