Install & Compatibility
Where this runs
tested against v1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.146s · 19.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.140s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
add_env_tag
✓ from yaml_env_tag import add_env_tag
The primary helper function to enable the !ENV tag on a PyYAML loader.
construct_env_tag
✓ from yaml_env_tag import construct_env_tag
Lower-level constructor function for direct integration with PyYAML's add_constructor method.
This quickstart demonstrates how to load YAML content containing `!ENV` tags, which resolve to environment variable values or specified defaults. It highlights the use of `add_env_tag` with `yaml.SafeLoader` for secure parsing and showcases both single variable and fallback sequence syntaxes. Set environment variables using `os.environ` before loading the YAML.
import yaml
import os
from yaml_env_tag import add_env_tag
# Create a YAML string with environment variable tags
yaml_content = """
database:
host: !ENV DB_HOST
port: !ENV [DB_PORT, 5432] # Uses 5432 if DB_PORT is not set
user: !ENV [DB_USER, default_user] # Uses 'default_user' if DB_USER is not set
api_key: !ENV [API_KEY_SECRET, FALLBACK_API_KEY, "no_api_key_set"]
"""
# Set some environment variables for testing
os.environ['DB_HOST'] = 'localhost'
os.environ['API_KEY_SECRET'] = 'my_super_secret_key'
# DB_PORT, DB_USER, and FALLBACK_API_KEY are intentionally not set to demonstrate fallbacks
# Get a PyYAML SafeLoader and add the environment tag constructor to it.
# It's crucial to use SafeLoader for security with untrusted YAML.
SafeEnvLoader = add_env_tag(yaml.SafeLoader)
# Load the YAML content
config = yaml.load(yaml_content, Loader=SafeEnvLoader)
print("Loaded Configuration:")
print(config)
# Clean up environment variables (good practice, especially in automated tests)
del os.environ['DB_HOST']
del os.environ['API_KEY_SECRET']
# Expected output:
# Loaded Configuration:
# {
# 'database': {'host': 'localhost', 'port': 5432, 'user': 'default_user'},
# 'api_key': 'my_super_secret_key'
# }
Errors
Common errors & fixes
ConstructorError: could not determine a constructor for the tag '!ENV'
The `!ENV` tag constructor from `pyyaml-env-tag` was not registered with the YAML loader, typically because `yaml.safe_load` or `yaml.load` was used instead of `pyyaml_env_tag.load`.
fixUse `pyyaml_env_tag.load` from the library instead of PyYAML's default loaders (e.g., `import pyyaml_env_tag; data = pyyaml_env_tag.load(yaml_string)`).
KeyError: 'MY_ENVIRONMENT_VARIABLE'
The YAML file references an environment variable using `!ENV MY_ENVIRONMENT_VARIABLE` that is not set in the shell or environment where the Python script is being executed.
fixSet the required environment variable before running your Python script (e.g., `export MY_ENVIRONMENT_VARIABLE="some_value"` in your terminal or ensure it's loaded from a `.env` file).
ModuleNotFoundError: No module named 'pyyaml_env_tag'
The `pyyaml-env-tag` library has not been installed in the Python environment being used, or the environment where the script is run differs from where it was installed.
fixInstall the library using pip: `pip install pyyaml-env-tag`.
Upgrade
Version history
1.1latest on PyPI · released May 13, 2025
Audit
Dependencies
pyyamlrequiredThis library extends PyYAML functionality, requiring it for YAML parsing and emitting.