Envier

0.6.1 verified Tue May 12 auth: no python install: verified quickstart: verified

Envier is a Python library for extracting configuration from environment variables in a declarative and 12-factor-app-compliant way. It focuses on type-hinting and clear definition of environment variable mappings to Python objects. The library is currently at version 0.6.1 and is actively maintained with regular releases.

pip install envier

Common errors

error ModuleNotFoundError: No module named 'envier' ↓

cause The 'envier' library has not been installed in the Python environment where the code is being run.

fix

Install the 'envier' library using pip: pip install envier

error envier.errors.MissingValueError: Required environment variable 'YOUR_VARIABLE_NAME' is not set. ↓

cause A configuration field defined in an `envier` dataclass is marked as required (by default, or explicitly with `default=...` not present) but the corresponding environment variable is not found.

fix

Set the environment variable YOUR_VARIABLE_NAME in your shell or .env file before running the application, or provide a default value in your envier configuration class, e.g., YOUR_VARIABLE_NAME: str = 'default_value' or YOUR_VARIABLE_NAME: str = field(default='default_value').

error envier.errors.InvalidTypeError: Environment variable 'YOUR_NUMBER_VARIABLE' ('abc') cannot be converted to <class 'int'>. ↓

cause The value of an environment variable cannot be converted to the Python type specified in the `envier` dataclass (e.g., 'abc' cannot be converted to an integer).

fix

Ensure the environment variable YOUR_NUMBER_VARIABLE contains a value that can be successfully converted to the declared type. For example, if it's an int, provide a string like '123' instead of 'abc'.

error AttributeError: 'Settings' object has no attribute 'missing_attribute' ↓

cause You are trying to access an attribute on your `envier` settings object that was not defined in its corresponding dataclass or is misspelled.

fix

Verify that the attribute missing_attribute is correctly defined in your envier dataclass (e.g., class Settings(Env): missing_attribute: str) and that you are using the correct casing and spelling when accessing it.

Warnings

breaking The internal structure and exposure of `HelpInfo` was refactored. Code directly importing `HelpInfo` or relying on its previous class-based implementation might break. ↓

fix Review the usage of `HelpInfo` and adapt to its new `namedtuple` structure. Consult the latest documentation for correct access.

breaking The Sphinx plugin for auto-generating environment variable documentation was removed. Users who relied on this feature will need to find an alternative documentation generation method. ↓

fix Migrate to a different documentation generation approach or manually maintain environment variable documentation.

gotcha There have been multiple bug fixes (v0.6.1, v0.2.1, v0.2.0) related to the handling of `include` with `namespace` and prefixes for sub-configuration items. Users should thoroughly test configurations involving nested structures and custom prefixes, as these areas have historically shown inconsistencies. ↓

fix Upgrade to the latest version to benefit from bug fixes. Carefully review and test configurations involving nested structures and prefixes.

gotcha A bug affecting the proper handling of `Optional` types in configuration variables was fixed in version 0.5.2. ↓

fix Ensure you are using `envier` version 0.5.2 or newer when defining configuration variables with `Optional[Type]`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 17.9M

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.02s 19.7M

3.11 alpine (musl) - - 0.03s 19.7M

3.11 slim (glibc) wheel 1.7s 0.02s 20M

3.11 slim (glibc) - - 0.02s 20M

3.12 alpine (musl) wheel - 0.02s 11.6M

3.12 alpine (musl) - - 0.02s 11.6M

3.12 slim (glibc) wheel 1.5s 0.02s 12M

3.12 slim (glibc) - - 0.02s 12M

3.13 alpine (musl) wheel - 0.01s 11.3M

3.13 alpine (musl) - - 0.01s 11.2M

3.13 slim (glibc) wheel 1.5s 0.02s 12M

3.13 slim (glibc) - - 0.02s 12M

3.9 alpine (musl) wheel - 0.01s 17.3M

3.9 alpine (musl) - - 0.01s 17.3M

3.9 slim (glibc) wheel 1.7s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

Env
```
from envier import Env
```

Quickstart verified last tested: 2026-04-24

This example demonstrates how to define a configuration class using `envier.Env`, specify environment variable mappings with `Env.var`, and handle prefixes for nested configurations. It sets temporary environment variables to ensure the example is runnable.

import os
from envier import Env

# Set environment variables for the example
os.environ['MYAPP_DEBUG'] = os.environ.get('MYAPP_DEBUG', 'True')
os.environ['MYAPP_SERVICE_HOST'] = os.environ.get('MYAPP_SERVICE_HOST', 'example.com')
os.environ['MYAPP_SERVICE_PORT'] = os.environ.get('MYAPP_SERVICE_PORT', '8080')

class GlobalConfig(Env):
    __prefix__ = "myapp"

    debug_mode = Env.var(bool, "debug", default=False)

    service_host = Env.var(str, "service.host", default="localhost")
    service_port = Env.var(int, "service.port", default=3000)

# Instantiate the configuration
config = GlobalConfig()

print(f"Debug Mode: {config.debug_mode}")
print(f"Service Host: {config.service_host}")
print(f"Service Port: {config.service_port}")

# Expected output if env vars are not set:
# Debug Mode: True
# Service Host: example.com
# Service Port: 8080

# Clean up environment variables (optional, but good for isolated testing)
del os.environ['MYAPP_DEBUG']
del os.environ['MYAPP_SERVICE_HOST']
del os.environ['MYAPP_SERVICE_PORT']