{"id":2970,"library":"hyperpyyaml","title":"HyperPyYAML","description":"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.","status":"active","version":"1.2.3","language":"python","source_language":"en","source_url":"https://github.com/speechbrain/HyperPyYAML","tags":["YAML","configuration","hyperparameters","speechbrain","data serialization","MLOps"],"install":[{"cmd":"pip install hyperpyyaml","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core YAML parsing.","package":"pyyaml","optional":false},{"reason":"Underlying YAML parsing, specific version required for compatibility.","package":"ruamel.yaml","optional":false}],"imports":[{"symbol":"load_hyperpyyaml","correct":"from hyperpyyaml import load_hyperpyyaml"}],"quickstart":{"code":"import torch\nfrom hyperpyyaml import load_hyperpyyaml\n\nexample_hyperparams_yaml = \"\"\"\nbase_channels: 32\nkernel_size: 11\npadding: !ref // 2\nlayer1: !new:torch.nn.Conv1d\n in_channels: 1\n out_channels: !ref \n kernel_size: !ref \n padding: !ref \nmodel: !new:torch.nn.Sequential\n - !ref \n - !new:torch.nn.LeakyReLU\n\"\"\"\n\n# Using load_hyperpyyaml to parse the YAML string\nloaded_hparams = load_hyperpyyaml(example_hyperparams_yaml)\n\nprint(loaded_hparams['base_channels'])\nprint(loaded_hparams['padding'])\nprint(loaded_hparams['model'])\n","lang":"python","description":"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."},"warnings":[{"fix":"Only load YAML files from trusted sources. Review any YAML configuration before using it with HyperPyYAML, especially files from external or untrusted origins.","message":"HyperPyYAML 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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"Compatibility issues with `ruamel.yaml` versions have occurred. Specifically, versions of `ruamel.yaml` 0.19.0 and above can cause breakage due to API changes.","severity":"breaking","affected_versions":"<1.2.3"},{"fix":"Upgrade to HyperPyYAML 1.2.3 or higher, where this issue has been resolved.","message":"The `!include` tag in older versions could break due to incorrect handling of overrides, particularly when no overrides were provided or the structure was unexpected.","severity":"gotcha","affected_versions":"<1.2.3"},{"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.","message":"The `!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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to HyperPyYAML 1.2.3 or higher for full Python 3.8+ compatibility.","message":"Older versions of HyperPyYAML had issues with Python 3.8+ compatibility, particularly concerning `ast.Constant`.","severity":"deprecated","affected_versions":"<1.2.3"}],"env_vars":null,"search_vec":"'1.2.3':30 'activ':24 'better':19 'bug':38 'configur':44 'data':47 'definit':21 'enhanc':13 'extend':8 'featur':42 'fix':39 'hyperparamet':20,45 'hyperpyyaml':1,2 'interact':14 'librari':6 'maintain':25 'mlop':49 'need':36 'new':41 'object':17 'python':5,16 'recent':28 'releas':33 'serial':48 'speechbrain':46 'syntax':11 'typic':32 'updat':34 'version':29 'yaml':10,43","created_at":"2026-04-11T09:15:24.590342+00:00","updated_at":"2026-04-16T15:39:38.341444+00:00","problems":[{"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`.","cause":"The `hyperpyyaml` library or one of its core dependencies, like `ruamel.yaml`, is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'hyperpyyaml'"},{"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.","cause":"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.","error":"TypeError: Expected to update a mapping, but got: [...] OR ValueError: (\"The structure of the overrides doesn't match the structure of the document: \", {...})"},{"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.","cause":"This error happens when YAML anchors, particularly in conjunction with `!new` or `!apply` tags, are duplicated within the YAML document during processing by HyperPyYAML.","error":"yaml.composer.ComposerError: found duplicate anchor 'idXXX'"},{"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`.","cause":"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.","error":"AttributeError: 'Loader' object has no attribute 'max_depth'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/speechbrain/HyperPyYAML","docs":null,"changelog":null,"pypi":"https://pypi.org/project/hyperpyyaml/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}