---
id: pyyaml-env-tag
version: "1.1"
license: MIT
license_treatment: permissive
maintenance: aging
---

# pyyaml-env-tag — A custom YAML tag for referencing environment variables in YAML files.

License: permissive · Maintenance: aging · Downloads: 17.2M/mo

## What it is and what it does

pyyaml_env_tag extends pyyaml with a custom `!ENV` tag that substitutes environment variable values directly into YAML during parsing. Instead of loading static config files, you can reference environment variables by name, and the tag will resolve them to their actual values at parse time. The package automatically coerces values using YAML's implicit type system—so an environment variable set to the string `true` becomes a Python boolean, not a string.

The tag supports fallback chains and defaults: you can specify multiple environment variables to try in order, with a final default value if none are set. This is useful for configuration management where you want environment-specific overrides but sensible defaults when variables aren't defined. The package depends only on pyyaml and integrates by wrapping your chosen loader with the `add_env_tag()` helper.

Use it for:

- Load database credentials from environment variables in a YAML config file without post-processing
- Provide environment-specific configuration by setting different env vars before parsing
- Define fallback values for optional settings that may or may not be set in the environment
- Avoid hardcoding secrets in config files by referencing them as env vars at parse time
- Coerce environment string values to booleans, integers, or null in YAML without manual conversion

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds a custom YAML tag that lets you reference environment variables directly in YAML files, with support for fallbacks and type coercion.

Yes, if you need to inject environment variables into YAML configs at parse time. The package is lightweight, has no security issues, and is stable. The aging maintenance status (458 days since last release) is not a blocker for a small, focused tool, but monitor the repo if you depend on active development. Install if your workflow benefits from env-var-aware YAML loading; skip if you prefer post-processing or template-based substitution.

## Install

pip install pyyaml-env-tag
uv add pyyaml-env-tag
poetry add pyyaml-env-tag

## Installing pyyaml-env-tag

Before you install: Low install friction with a single pure-Python dependency. Maintenance status is aging—last release was 458 days ago—but the repo is active and marked Production/Stable.

License in practice: MIT license (permissive) means you can use this freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install pyyaml-env-tag

from pyyaml_env_tag import add_env_tag
import pyyaml

myLoader = add_env_tag(pyyaml.Loader)
pyyaml.load('key: !ENV MY_VAR', Loader=myLoader)

Verify before relying:

- Whether environment variable parsing handles all YAML scalar types correctly in edge cases
- Performance characteristics when processing large YAML files with many env tags

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 17.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

yaml environment variables, env tag yaml, yaml config from environment, environment substitution yaml, yaml env variable reference, environment variable yaml loader, yaml environment fallback, yaml-config, environment-variables

[View on SkillFed](https://skillfed.io/packages/pyyaml-env-tag) · [View on PyPI](https://pypi.org/project/pyyaml-env-tag/)