---
id: hyperpyyaml
version: "1.2.3"
license: unclear
license_treatment: permissive
maintenance: aging
---

# HyperPyYAML — Extensions to YAML syntax for better python interaction

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

## What it is and what it does

HyperPyYAML is a YAML extension library that adds Python-specific syntax to make configuration files more expressive and less repetitive. It lets you instantiate Python objects directly in YAML using `!new:` tags, define reusable references with `!ref` that support string interpolation and nested lookups, and implicitly parse tuples from parenthesized strings. The package depends on pyyaml and ruamel.yaml as runtime dependencies.

It's designed for data-analysis workflows where hyperparameters need to be easily examined, modified, and cross-referenced without cluttering Python code. You load a YAML file with `load_hyperpyyaml()`, optionally override values at runtime, and get back a fully-constructed configuration object with all references resolved and objects instantiated. The trade-off is that loading YAML allows arbitrary code execution—a feature, not a bug, but one that requires you to trust or audit any YAML files you load.

Use it for:

- Define machine-learning experiment hyperparameters in YAML with cross-references that auto-update when you change a base value.
- Instantiate complex nested objects (models, counters, custom classes) directly in configuration files without Python boilerplate.
- Override specific hyperparameters at runtime (e.g., learning rate, batch size) without editing the YAML file itself.
- Share reproducible experiment configs that reference each other and compute derived values via interpolation.
- Avoid scattering magic numbers and object constructors throughout Python analysis code by centralizing them in a single YAML file.

## Worth the install?

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

Extends YAML syntax with Python-friendly features like object instantiation, smart aliases with interpolation, and implicit tuple support for cleaner hyperparameter configuration files.

Yes, if you manage hyperparameter-heavy projects and want cleaner, more maintainable config files. The low install friction, permissive license, and active repository make it a safe choice. Be aware that loading YAML executes arbitrary Python code—audit any untrusted configs. Aging maintenance status suggests stable rather than rapidly evolving, which is appropriate for a focused utility.

## Install

pip install hyperpyyaml
uv add hyperpyyaml
poetry add hyperpyyaml

## Installing HyperPyYAML

Before you install: Low friction—pure Python wheel with just two YAML library dependencies (pyyaml and ruamel.yaml). Last release was recent; repo is active and not archived, though maintenance status is aging.

License in practice: Licensed under Apache 2.0 (permissive). No restrictions on commercial or private use; attribution required but no copyleft obligations.

Quickstart:

pip install hyperpyyaml

from hyperpyyaml import load_hyperpyyaml

yaml_str = """model: !new:collections.Counter
folder: abc/def
ref_folder: !ref /"""
config = load_hyperpyyaml(yaml_str)
print(config['model'])

Loading untrusted YAML files allows arbitrary code execution—verify all YAML sources before loading, as documented in the package's security note.

Verify before relying:

- Whether the package works with all modern Python versions (requires_python is unspecified in metadata).
- Current maintenance velocity and whether aging status indicates reduced active development or stable maintenance.

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 1.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

yaml hyperparameter configuration, python yaml extensions, yaml object instantiation, yaml string interpolation, experiment config files, yaml with python objects, hyperparameter yaml loader, configuration-management, hyperparameter-tuning, yaml-extensions

[View on SkillFed](https://skillfed.io/packages/hyperpyyaml) · [View on PyPI](https://pypi.org/project/hyperpyyaml/)