Mastering envyaml: A Practical Playbook for YAML Configs with Environment Variables

Key Takeaways

• envyaml is a lightweight Python library that loads YAML configuration files and seamlessly substitutes environment variables.
• Installation is a single pip install envyaml command.
• Use envyaml.load to read a file, then reference values like a normal dictionary.
• envyaml supports nested interpolation, default values, and custom loaders.
• It outperforms python-dotenv for YAML files, and is simpler than pydantic for configuration parsing.
• Follow the checklist below to avoid common pitfalls and ensure secure, maintainable configs.

Why envyaml?

Modern Python applications often require flexible configuration that can change between environments (dev, staging, prod). YAML files provide readability, while environment variables keep secrets out of source control. envyaml bridges the two, allowing you to:

• Write a single YAML file for all environments.
• Inject environment-specific values without duplication.
• Keep secrets in .env files or container secrets.

Installation & Setup

Step 1: Install the Package

pip install envyaml

Step 2: Create a YAML Config

# config.yaml
database:
  host: ${DB_HOST}
  port: ${DB_PORT:5432}
  user: ${DB_USER}
  password: ${DB_PASSWORD}
logging:
  level: ${LOG_LEVEL:INFO}
  file: /var/log/app.log

Step 3: Load the Config in Your Code

from envyaml import load

config = load("config.yaml")
print(config["database"]["host"])

Advanced Features

Custom Default Values

Use ${VAR:default} syntax to provide a fallback when an environment variable is missing.

Nested Interpolation

envyaml automatically resolves nested variables, e.g., ${BASE_URL}/api where BASE_URL is defined elsewhere.

Custom Loaders

For complex scenarios, you can pass a custom loader to load:

from envyaml import load
from yaml import SafeLoader

config = load("config.yaml", loader=SafeLoader)

Best Practices Checklist

• ✅ Keep secrets in environment variables, never in config.yaml.
• ✅ Use default values for non-sensitive settings.
• ✅ Validate configuration at startup (e.g., using pydantic or custom checks).
• ✅ Store a config.example.yaml in the repo to document required variables.
• ✅ Use dotenv or Docker secrets to inject variables into the runtime environment.
• ✅ Avoid hardcoding file paths; use relative paths or environment variables.
• ✅ Log the loaded configuration (masking secrets) to aid debugging.

Comparison with Other Config Libraries

Feature	envyaml	python-dotenv	pydantic
File Format	YAML	dotenv (.env)	JSON / Pydantic models (YAML via pyyaml)
Environment Variable Interpolation	✔️ Built-in	✔️ Built-in	✔️ via custom validators
Nested Configs	✔️	✖️	✔️ (via models)
Validation	✖️ (manual)	✖️	✔️ (built-in)
Installation Size	~10 KB	~5 KB	~200 KB
Use Case	Lightweight YAML configs with env vars	Simple .env files	Complex typed schemas

FAQs

1. How do I secure my secrets when using envyaml?

Never store secrets directly in the YAML file. Use environment variables, dotenv files (excluded from version control), or container secrets. envyaml will replace placeholders with the values from the environment at runtime.

2. Can I use envyaml with Docker Compose?

Yes. Define the environment variables in the docker-compose.yml or in a .env file. When the container starts, envyaml will resolve the placeholders automatically.

3. Does envyaml support validation of config values?

Not directly. For validation, combine envyaml with pydantic or a custom validation function. Load the YAML with envyaml, then pass the resulting dictionary to a pydantic model for type checking and validation.