Env Magic (v1)

The Environment Wizard (EnvWizard) is a dataclass mixin for loading typed configuration from:

• environment variables

• .env files

• secret directories

It performs string-to-type coercion, validates input, and in v1 supports nested dataclasses.

Important

EnvWizard v1 is opt-in. If you do not enable it, v0 behavior applies.

Hint

This page documents v1 concepts: explicit precedence, v1 aliasing, and nested dataclass support.

Why v1?

In v0, environment lookup relied on implicit heuristics and cascading fallbacks. That made behavior harder to reason about and customize safely.

v1 introduces:

• explicit environment precedence

• clearer aliasing rules (load vs dump)

• first-class nested dataclass support

Installation

Install the base package:

pip install dataclass-wizard

Optional extras:

pip install dataclass-wizard[dotenv]
pip install dataclass-wizard[tz]

Opting into v1

Enable v1 via the inner Meta class:

from dataclass_wizard.v1 import EnvWizard

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True

    token: str

Or using EnvMeta:

from dataclass_wizard import EnvMeta
from dataclass_wizard.v1 import EnvWizard

class Config(EnvWizard):
    token: str

EnvMeta(v1=True).bind_to(Config)

Quick Start

import os
from dataclass_wizard.v1 import EnvWizard

os.environ.update({
    "APP_NAME": "Env Wizard",
    "MAX_CONNECTIONS": "10",
    "DEBUG": "true",
})

class AppConfig(EnvWizard):
    app_name: str
    max_connections: int
    debug: bool

cfg = AppConfig()

assert cfg.app_name == "Env Wizard"
assert cfg.max_connections == 10
assert cfg.debug is True

Environment Precedence

v1 resolves values from multiple sources using an explicit precedence order.

Default precedence:

Secrets → Environment → Dotenv

Later sources override earlier sources.

Customize precedence:

from dataclass_wizard.v1 import EnvWizard
from dataclass_wizard.v1.enums import EnvPrecedence

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        v1_env_precedence = EnvPrecedence.SECRETS_DOTENV_ENV

    token: str

Dotenv Support

Enable .env loading via Meta.env_file:

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        env_file = True

    api_key: str

Custom paths are supported:

from pathlib import Path

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        env_file = Path(".env.prod")

    db_host: str

If multiple files are provided, later files take precedence.

Secrets Directories

Secrets directories treat filenames as keys and file contents as values.

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        secrets_dir = "/run/secrets"

    db_password: str

Field Aliases (v1)

Load-only aliases (recommended):

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        v1_field_to_env_load = {
            "db_url": ["DATABASE_URL", "DB_URL"],
        }

    db_url: str

Dump-only aliases:

class _(EnvWizard.Meta):
    v1_field_to_alias_dump = {
        "db_url": "databaseUrl",
    }

Hint

Loading and dumping are intentionally separate concerns in v1.

Prefixes

Static prefix:

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True
        env_prefix = "APP_"

    name: str

Dynamic override at runtime:

Config(_env_prefix="CUSTOM_")

Nested Dataclasses (v1)

v1 supports nested dataclasses out of the box.

class DB(EnvWizard):
    host: str
    port: int

class Config(EnvWizard):
    class _(EnvWizard.Meta):
        v1 = True

    db: DB

Environment variables:

DB_HOST=localhost
DB_PORT=5432

Error Handling

Common errors include:

• MissingVars: required value not found

• ParseError: type conversion failed

• UnknownKeyError: unknown key (if enabled)

Enable debug output:

class _(EnvWizard.Meta):
    v1_debug = True