---
id: environ-config
version: "26.1.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# environ-config — Boilerplate-free configuration with env variables.

License: permissive · Maintenance: active · Downloads: 198.2K/mo

## What it is and what it does

environ-config is a Python library that maps environment variables into typed, validated configuration objects using declarative class definitions. It builds on attrs to provide automatic data validation and conversion, eliminating boilerplate code typically needed for environment-based config. The package follows the Twelve-Factor App methodology and supports nested configuration from flat environment variable names, default and mandatory values, and pluggable secrets extraction from HashiCorp Vault, AWS Secrets Manager, or INI files.

You define your config as a class with environ.var() and environ.bool_var() fields, optionally nested with environ.group(), then call environ.to_config() to populate it from os.environ or a custom dict. The library handles type conversion (e.g., string to int), boolean parsing (recognizing 'true', 'yes', '1'), and validation through attrs converters and validators. It also generates helpful debug logging showing which variables are present and what the library is looking for.

Use it for:

- Manage multi-environment application settings (dev, staging, prod) by reading from environment variables without hardcoding or config files.
- Extract database credentials and API keys from Vault or AWS Secrets Manager into a typed config object with validation.
- Build nested configuration hierarchies (e.g., separate DB, cache, and logging sections) from flat environment variable names.
- Enforce required config fields and provide sensible defaults without writing validation logic.
- Generate dynamic help documentation for environment variables your application expects.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Loads application configuration from environment variables using declarative Python classes, with support for nested config, type conversion, validation, and pluggable secrets extraction.

Yes. Low install friction, active maintenance, permissive license, no known vulnerabilities, and production-stable status make it a safe choice. Install if you need declarative, type-safe environment-based configuration with minimal boilerplate—especially valuable in containerized or cloud-native deployments following Twelve-Factor principles. Requires Python 3.10+.

## Install

pip install environ-config
uv add environ-config
poetry add environ-config

## Installing environ-config

Before you install: Low install friction—a pure Python wheel with only attrs as a runtime dependency. Actively maintained as of 23 days ago with production-stable status.

License in practice: Apache 2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install environ-config

import environ

@environ.config(prefix="APP")
class AppConfig:
    env = environ.var()
    debug = environ.bool_var()

cfg = environ.to_config(AppConfig, environ={"APP_ENV": "prod", "APP_DEBUG": "no"})

Requires Python 3.10 or later; support for Python 3.8 and 3.9 was removed in version 26.1.0.

Verify before relying:

- Whether boto3 is automatically installed for AWS Secrets Manager support or must be added separately.
- Performance characteristics when dealing with large numbers of environment variables or deeply nested config structures.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 198.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

environment variable configuration, env config loader, twelve factor app config, declarative config from env, nested environment configuration, config with attrs, secrets from environment, configuration-management, environment-variables, twelve-factor

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