pyaml-env

What it is and what it does

pyaml-env is a thin wrapper around PyYAML that adds environment variable resolution to YAML configuration files. It lets you mark values with a custom tag (default !ENV) and substitute environment variables at parse time, keeping secrets out of version control. The library supports default values using a separator (default :), custom YAML loaders, type coercion via YAML's standard type tags, and attribute-style access through a BaseConfig wrapper.

Typical use: define a YAML config with placeholders like `password: !ENV ${DB_PASS:fallback}`, set environment variables before running your app, then call parse_config() to get a dictionary with all variables resolved. If a variable is unset and has no default, it becomes 'N/A' by default—or you can raise an error instead with raise_if_na=True.

Use it for:

• Load database credentials from environment variables in a YAML config without hardcoding secrets.
• Manage different configurations per deployment environment (dev, staging, prod) by varying environment variables.
• Provide default fallback values for optional config parameters while requiring critical ones to be set.
• Parse YAML files containing serialized Python objects using a custom loader like yaml.UnsafeLoader.
• Access nested config values as attributes (e.g., config.database.url) via BaseConfig wrapper.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses YAML configuration files and resolves environment variables marked with a custom tag, allowing secrets to be injected at runtime rather than stored in plain text.

Yes, if you use YAML for configuration and need to inject secrets via environment variables. The package is lightweight, has no security vulnerabilities, and solves a common deployment pattern. Dormant maintenance is acceptable for a stable, single-purpose tool. Install if your workflow already involves YAML and environment-based secrets; skip if you prefer .env files or other config systems.

Install

pyaml-env on PyPI

pip install pyaml-env

uv add pyaml-env

poetry add pyaml-env

Installing pyaml-env

Before you install

Low friction: single runtime dependency (PyYAML), pure Python wheel, dormant maintenance status (last commit 2025-01-13, 578 days since release) but no active issues flagged.

License in practice

MIT license (permissive) — you can use, modify, and distribute freely with minimal restrictions.

Quickstart

pip install pyaml-env

from pyaml_env import parse_config
config = parse_config('config.yaml')
# YAML file contains: username: !ENV ${DB_USER}
# Resolves to: config['username'] = os.environ['DB_USER']

Environment variables must be set before parse_config() is called; unset variables without defaults resolve to 'N/A' by default.

Verify before relying

• Whether the package handles concurrent or multi-threaded config loading safely.
• Performance characteristics when parsing large YAML files with many environment variable substitutions.
• Compatibility with YAML anchors, aliases, and other advanced YAML features alongside environment variable tags.

Package facts

Evidence: pyaml_env-1.2.2-py3-none-any.whl

Tags

More Utilities packages