{"id":9040,"library":"hydra-zen","title":"hydra-zen: Composable Hydra Configurations","description":"hydra-zen is a Python library that simplifies the creation of reproducible, composable, and scalable configurations for machine learning and scientific workflows using Hydra. It provides a more Pythonic API to define Hydra configurations, enabling type-checking, autocompletion, and easier integration with existing Python code. The current version is 0.16.0, with releases occurring periodically, often driven by new features or compatibility updates.","status":"active","version":"0.16.0","language":"en","source_language":"en","source_url":"https://github.com/mit-ll-responsible-ai/hydra-zen","tags":["Hydra","Configuration","Machine Learning","MLOps","Reproducibility","Pydantic"],"install":[{"cmd":"pip install hydra-zen","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for core configuration management and CLI integration.","package":"hydra-core","optional":false},{"reason":"Optional, enables Pydantic-powered type-checking and validation for configs.","package":"pydantic","optional":true}],"imports":[{"symbol":"zen","correct":"from hydra_zen import zen"},{"symbol":"builds","correct":"from hydra_zen import builds"},{"symbol":"make_config","correct":"from hydra_zen import make_config"},{"symbol":"instantiate","correct":"from hydra_zen import instantiate"},{"symbol":"store","correct":"from hydra_zen import store"}],"quickstart":{"code":"from hydra_zen import builds, instantiate\nfrom omegaconf import OmegaConf\n\ndef train_model(epochs: int, lr: float, model_name: str = \"ResNet\"): #_target_\n    \"\"\"Simulates a model training process.\"\"\"\n    return f\"Training {model_name} for {epochs} epochs with learning rate {lr}\"\n\n# Define a config for our function, setting default values\n# Parameters not set here become mandatory CLI arguments or must have defaults in the function.\nTrainConfig = builds(train_model, epochs=10, lr=0.01, model_name=\"AwesomeNet\")\n\n# Instantiate the configuration directly to run the target function\n# This simulates `hydra.utils.instantiate` using hydra-zen's convenience API\nresult = instantiate(TrainConfig)\nprint(f\"Direct instantiation: {result}\")\n\n# You can also override values programmatically\noverride_config = TrainConfig(epochs=20, lr=0.005, model_name=\"SuperNet\")\nresult_override = instantiate(override_config)\nprint(f\"Instantiation with overrides: {result_override}\")\n\n# Inspect the raw OmegaConf config object\nprint(\"\\nGenerated config:\\n\" + OmegaConf.to_yaml(override_config))","lang":"python","description":"This quickstart demonstrates how to define a configuration for a Python function using `builds` and then instantiate that configuration directly using `instantiate`. It shows how to set default parameters and how to override them programmatically, illustrating `hydra-zen`'s ability to create and manage `_target_` configurations."},"warnings":[{"fix":"Review any custom `_target_wrapper_` implementations or complex partial instantiation patterns. Test your application carefully after upgrading.","message":"The `_target_wrapper_` behavior for partial instantiation was improved/changed in v0.15.0. If you relied on the exact previous behavior of custom target wrappers, this might subtly alter how partially constructed objects resolve.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"If upgrading from <0.13.0, thoroughly test applications using advanced type-checking or validation. Consider explicitly disabling Pydantic integration if it causes unexpected issues, or adapt your code to leverage the new Pydantic-based validation.","message":"Version 0.13.0 introduced Pydantic integration. While largely additive, this changed internal type representation and validation capabilities. Users with custom validation logic or deep introspection of config types might observe changes or new validation errors if Pydantic is enabled.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Familiarize yourself with the official `hydra-core` documentation, especially the concepts of instantiation and composition, in conjunction with `hydra-zen`'s streamlined API.","message":"`hydra-zen` is an abstraction layer over `hydra-core`. A solid understanding of Hydra's core concepts (e.g., `_target_`, `_recursive_`, config groups, CLI overrides) is crucial for effective use and debugging, as `hydra-zen` simplifies the API but does not eliminate the underlying complexities.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `@zen` for your main application entry point (typically `main.py`) that expects Hydra CLI arguments. Use `instantiate()` when you need to programmatically create an object from a config within your code without invoking the full Hydra application context.","message":"Distinction between `zen.zen` decorator and `instantiate`: The `@zen` decorator creates a Hydra entry point for command-line execution, while `instantiate()` is for programmatic object creation from configs. Confusing these can lead to `MissingMandatoryValue` errors or difficulty running without the Hydra CLI.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install hydra-zen` to install the library.","cause":"The `hydra-zen` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'hydra_zen'"},{"fix":"Ensure all parameters for the target function have defaults in the `builds` call or in the function signature. If running via Hydra CLI, provide missing parameters: `python your_app.py path.to.param=value`.","cause":"A parameter required by a `builds` configuration or a decorated function (either implicitly via `_target_` or explicitly defined) was not provided a default value in the config nor via Hydra's CLI.","error":"omegaconf.errors.MissingMandatoryValue: Missing mandatory value ${some_param}"},{"fix":"Use `instantiate(ConfigObject)` to create an instance of the target object. Configuration objects are not directly callable.","cause":"Attempting to directly call a configuration object returned by `builds` or `make_config` as if it were the target function itself, instead of using `instantiate`.","error":"TypeError: 'Config' object is not callable"},{"fix":"Add the necessary import statement at the top of your script, e.g., `from hydra_zen import builds, zen, instantiate`.","cause":"The `builds` (or `zen`, `instantiate`, etc.) symbol was not imported from `hydra_zen`.","error":"NameError: name 'builds' is not defined"}]}