---
id: environs
version: "15.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# environs — simplified environment variable parsing

License: permissive · Maintenance: active · Downloads: 5.2M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 5.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

environment variable parsing, config from env vars, type-cast environment variables, .env file loading, environment configuration, validate env variables, twelve-factor config, configuration-management, env-vars

[View on SkillFed](https://skillfed.io/packages/environs) · [View on PyPI](https://pypi.org/project/environs/)