hyperpyyaml

library1.2.3pypypi✓ verified 23d ago

HyperPyYAML is a Python library that extends the YAML syntax for enhanced interaction with Python objects and better hyperparameter definition. It is actively maintained, with a recent version 1.2.3, and typically releases updates as needed for bug fixes and new features.

serialization ai-ml

pip install hyperpyyaml

github ↗package ↗

INSTALL

IMPORT

SIG · HYPERPYYAML

hyperpyyaml

serializationpythonv1.2.3

Install

2.1s avg

Import

284ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.3 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.292s · 22.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.1s · import 0.276s · 25MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

load_hyperpyyaml

✓ from hyperpyyaml import load_hyperpyyaml

This quickstart demonstrates how to load a YAML string containing HyperPyYAML extensions. It shows the use of `!ref` for referencing other parameters and `!new` for instantiating Python objects (like PyTorch modules) directly from the YAML.

import torch from hyperpyyaml import load_hyperpyyaml example_hyperparams_yaml = """ base_channels: 32 kernel_size: 11 padding: !ref <kernel_size> // 2 layer1: !new:torch.nn.Conv1d in_channels: 1 out_channels: !ref <base_channels> kernel_size: !ref <kernel_size> padding: !ref <padding> model: !new:torch.nn.Sequential - !ref <layer1> - !new:torch.nn.LeakyReLU """ # Using load_hyperpyyaml to parse the YAML string loaded_hparams = load_hyperpyyaml(example_hyperparams_yaml) print(loaded_hparams['base_channels']) print(loaded_hparams['padding']) print(loaded_hparams['model'])

Debug

Known issues

breakingHyperPyYAML allows arbitrary code execution through its custom tags, which is a feature for flexible configuration. Treat all YAML files loaded with HyperPyYAML as you would Python code. Loading untrusted YAML files can lead to security vulnerabilities.

fix

Only load YAML files from trusted sources. Review any YAML configuration before using it with HyperPyYAML, especially files from external or untrusted origins.

affects: All versions

breakingCompatibility issues with `ruamel.yaml` versions have occurred. Specifically, versions of `ruamel.yaml` 0.19.0 and above can cause breakage due to API changes.

fix

Upgrade HyperPyYAML to version 1.2.3 or newer, which explicitly pins `ruamel.yaml<0.19.0` in its dependencies to ensure compatibility. If manually managing dependencies, ensure `ruamel.yaml` is below `0.19.0`.

affects: <1.2.3

gotchaThe `!include` tag in older versions could break due to incorrect handling of overrides, particularly when no overrides were provided or the structure was unexpected.

fix

Upgrade to HyperPyYAML 1.2.3 or higher, where this issue has been resolved.

affects: <1.2.3

gotchaThe `!ref` tag creates a shallow reference to the original YAML node, meaning changes to the referenced object will affect all references. If a deep copy is desired, use the `!copy` tag instead.

fix

Always use `!copy` when you need an independent instance of an object or value, ensuring that modifications to one do not unexpectedly alter others.

affects: All versions

deprecatedOlder versions of HyperPyYAML had issues with Python 3.8+ compatibility, particularly concerning `ast.Constant`.

fix

Upgrade to HyperPyYAML 1.2.3 or higher for full Python 3.8+ compatibility.

affects: <1.2.3

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hyperpyyaml'

The `hyperpyyaml` library or one of its core dependencies, like `ruamel.yaml`, is not installed in the current Python environment.

fix

Install the library and its dependencies using pip: `pip install hyperpyyaml` or if specifically `ruamel.yaml` is missing or outdated, `pip install ruamel.yaml`.

TypeError: Expected to update a mapping, but got: [...] OR ValueError: ("The structure of the overrides doesn't match the structure of the document: ", {...})

This error often occurs when using the `!include` tag in a YAML file that resolves to a non-mapping type (e.g., a list), and `overrides` are provided that expect a mapping structure or don't correctly match the included document's structure.

fix

Ensure that the YAML structure at the point of inclusion (where `!include` is used) matches the expected type for updates (usually a mapping/dictionary) and that any `overrides` provided are compatible with the structure of the included YAML. If the included file is a list, avoid applying dictionary-like overrides directly to it.

yaml.composer.ComposerError: found duplicate anchor 'idXXX'

This error happens when YAML anchors, particularly in conjunction with `!new` or `!apply` tags, are duplicated within the YAML document during processing by HyperPyYAML.

fix

Review the YAML file for duplicate anchor definitions (`&anchor_name`) and ensure each anchor used for objects or applied functions has a unique name.

AttributeError: 'Loader' object has no attribute 'max_depth'

This indicates a version incompatibility between `hyperpyyaml` and its underlying YAML parser, `ruamel.yaml`. A newer version of `ruamel.yaml` might have removed or changed the `max_depth` attribute that `hyperpyyaml` expects.

fix

Pin the version of `ruamel.yaml` to a compatible one, as suggested in related issues. For example, `pip install 'ruamel.yaml<0.19.0'` or `pip install hyperpyyaml==1.2.3 ruamel.yaml<0.19.0`.

Upgrade

Version history

1.2.3latest on PyPI · released Jan 1, 2026

Audit

Dependencies

pyyamlrequiredCore YAML parsing.

ruamel.yamlrequiredUnderlying YAML parsing, specific version required for compatibility.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/speechbrain/HyperPyYAML ↗

packagehttps://pypi.org/project/hyperpyyaml/ ↗