epicenv 1.6.2

Schema-based environment variable management for Python projects

epicenv

Stop maintaining .env.example files that drift out of sync with reality. epicenv is a schema-based environment variable manager for Python: declare your variables once in pyproject.toml (or a dedicated .env.toml) with types, defaults, initializers, and help text. Generate fresh .env files for new contributors with one command, and catch missing or malformed values before they hit production.

Table of Contents

• Installation
• Quick Start
• Why epicenv?
• CLI Commands
• Schema Basics
• Built-in Initializers
• Framework Examples
• Validation
• Documentation

Installation

# Run without installing
uvx epicenv create

# Or install as a dependency
uv add epicenv

# For Django projects (adds dj-database-url, dj-email-url support)
uv add epicenv[django]

Quick Start

1. Define your schema in pyproject.toml:

[tool.epicenv.variables]
SECRET_KEY = {
    type = "str",
    required = true,
    help_text = "Secret key for cryptographic signing",
    initial_func = "epicenv.initializers.url_safe_password"
}

DEBUG = { type = "bool", default = false, initial = "on" }
DATABASE_URL = { type = "str", default = "sqlite:///db.sqlite3" }

2. Generate your .env file:

uvx epicenv create

3. Use in your code:

from epicenv import Env

env = Env()
env.read_env()

SECRET_KEY = env.str("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)

Why epicenv?

Traditional .env.example workflow	With epicenv
Copy .env.example to .env	Run epicenv create
Manually generate secrets	Auto-generated via initializers
Templates get out of date	Schema is the single source of truth
Runtime errors from missing vars	epicenv validate catches mistakes early
No documentation for variables	Help text in schema, shown in .env

CLI Commands

epicenv create                    # Create .env from schema
epicenv create --path config/.env # Create at specific path
epicenv create --no-backup        # Don't backup existing file

epicenv diff                      # Compare .env with schema
epicenv validate                  # Validate environment against schema
epicenv validate --strict         # Exit with error if validation fails

epicenv secrets get op://vault/item/field          # Fetch a single secret
epicenv secrets get op://vault/item --fields a,b,c # Fetch multiple fields as JSON
epicenv create-superuser                           # Create Django superuser (stdin/env/flags)

Platform note: epicenv create-superuser auto-detects piped JSON on stdin using select(), which is a POSIX primitive. On Windows the detection degrades to "no stdin," so Windows users should pass credentials via env vars (DJANGO_SUPERUSER_*) or explicit flags rather than piping JSON.

Schema Basics

Define variables in [tool.epicenv.variables]:

[tool.epicenv.variables]
MY_VAR = {
    type = "str",              # Required: str, bool, int, list, url, json, etc.
    required = true,           # Is this required? (default: true if no default)
    default = "value",         # Default for .env generation
    help_text = "Description", # Shown in generated .env
    initial = "value",         # Static initial value
    initial_func = "module.fn" # Dynamic initial value generator
}

Supported types: str, bool, int, float, list, dict, json, url, uuid, path, date, datetime, log_level, and Django types (dj_db_url, dj_email_url, dj_cache_url).

Schema location

For projects with many variables, keep pyproject.toml tidy by moving the schema into a dedicated .env.toml file next to pyproject.toml. It's auto-discovered — no pyproject.toml change needed:

# .env.toml
[variables]
DEBUG = { type = "bool", default = false, initial = "on" }

# Table form is nice for variables with several fields:
[variables.SECRET_KEY]
type = "str"
required = true
help_text = "Secret key for cryptographic signing"
initial_func = "epicenv.initializers.url_safe_password"

Or point at a custom path:

# pyproject.toml
[tool.epicenv]
config_file = "config/env-schema.toml"

See Schema Reference for complete field documentation and discovery rules.

Built-in Initializers

url_safe_password

Generate URL-safe random passwords:

SECRET_KEY = {
    type = "str",
    initial_func = "epicenv.initializers.url_safe_password"
}

# Custom length (default: 50)
API_TOKEN = {
    type = "str",
    initial_func = "epicenv.initializers.url_safe_password",
    kwargs = { length = 32 }
}

1Password

Fetch secrets from 1Password CLI during .env generation:

STRIPE_API_KEY = {
    type = "str",
    initial_func = "epicenv.initializers.onepassword",
    args = ["op://Production/Stripe/api_key"]
}

Requires 1Password CLI installed and signed in. Falls back to placeholder if unavailable.

See 1Password Integration for setup and troubleshooting.

Custom Initializers

Use any Python callable:

SECRET_KEY = { type = "str", initial_func = "secrets.token_urlsafe" }
DJANGO_KEY = { type = "str", initial_func = "django.core.management.utils.get_random_secret_key" }
CUSTOM = { type = "str", initial_func = "myapp.utils.generate_key" }

Framework Examples

Django

# pyproject.toml
[tool.epicenv.variables]
SECRET_KEY = { type = "str", required = true, initial_func = "django.core.management.utils.get_random_secret_key" }
DEBUG = { type = "bool", default = false, initial = "on" }
DATABASE_URL = { type = "dj_db_url", default = "sqlite:///db.sqlite3" }

# settings.py
from epicenv import Env

env = Env()
env.read_env()

SECRET_KEY = env.str("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)
DATABASES = {"default": env.dj_db_url("DATABASE_URL", default="sqlite:///db.sqlite3")}

See Django Integration for complete setup including email and cache URLs.

FastAPI / Flask

# pyproject.toml
[tool.epicenv.variables]
APP_NAME = { type = "str", default = "My API" }
API_HOST = { type = "str", default = "0.0.0.0" }
API_PORT = { type = "int", default = 8000 }
DATABASE_URL = { type = "url", required = true }
LOG_LEVEL = { type = "log_level", default = "INFO" }

# config.py
from epicenv import Env

env = Env()
env.read_env()

APP_NAME = env.str("APP_NAME", default="My API")
DATABASE_URL = env.url("DATABASE_URL")
LOG_LEVEL = env.log_level("LOG_LEVEL", default="INFO")

Validation

epicenv validates that variables used in code are defined in your schema. Control with EPICENV_VALIDATE:

Mode	Behavior
auto (default)	Validate when DEBUG=true
strict	Always validate, raise errors
warn	Always validate, warn only
off	Disable validation

EPICENV_VALIDATE=strict python app.py  # Always validate

Documentation

• Schema Reference - Complete field types and options
• 1Password Integration - Setup and troubleshooting
• Field Mapping Guide - Transform and map secrets with jq
• Django Integration - Django-specific features and legacy commands

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Acknowledgments

epicenv is built on top of environs, which provides the core environment variable parsing functionality.

License

MIT License