hydra-zen

library0.16.0pypypi✓ verified 84d ago

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.

ai-ml data devops workflow

pip install hydra-zen

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HYDRA-ZEN

hydra-zen

ai-mlpythonv0.16.0

Install

3.2s avg

Import

660ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.0 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.678s · 26.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.2s · import 0.641s · 28MB

25MB installed

● package 25MB

Code

Verified usage

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

zen

✓ from hydra_zen import zen

builds

✓ from hydra_zen import builds

make_config

✓ from hydra_zen import make_config

instantiate

✓ from hydra_zen import instantiate

store

✓ from hydra_zen import store

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.

from hydra_zen import builds, instantiate from omegaconf import OmegaConf def train_model(epochs: int, lr: float, model_name: str = "ResNet"): #_target_ """Simulates a model training process.""" return f"Training {model_name} for {epochs} epochs with learning rate {lr}" # Define a config for our function, setting default values # Parameters not set here become mandatory CLI arguments or must have defaults in the function. TrainConfig = builds(train_model, epochs=10, lr=0.01, model_name="AwesomeNet") # Instantiate the configuration directly to run the target function # This simulates `hydra.utils.instantiate` using hydra-zen's convenience API result = instantiate(TrainConfig) print(f"Direct instantiation: {result}") # You can also override values programmatically override_config = TrainConfig(epochs=20, lr=0.005, model_name="SuperNet") result_override = instantiate(override_config) print(f"Instantiation with overrides: {result_override}") # Inspect the raw OmegaConf config object print("\nGenerated config:\n" + OmegaConf.to_yaml(override_config))

Debug

Known issues

breakingThe `_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.

fix

Review any custom `_target_wrapper_` implementations or complex partial instantiation patterns. Test your application carefully after upgrading.

affects: >=0.15.0

breakingVersion 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.

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.

affects: >=0.13.0

gotcha`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.

fix

Familiarize yourself with the official `hydra-core` documentation, especially the concepts of instantiation and composition, in conjunction with `hydra-zen`'s streamlined API.

affects: All

gotchaDistinction 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.

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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hydra_zen'

The `hydra-zen` package is not installed in the current Python environment.

fix

Run `pip install hydra-zen` to install the library.

omegaconf.errors.MissingMandatoryValue: Missing mandatory value ${some_param}

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.

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`.

TypeError: 'Config' object is not callable

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`.

fix

Use `instantiate(ConfigObject)` to create an instance of the target object. Configuration objects are not directly callable.

NameError: name 'builds' is not defined

The `builds` (or `zen`, `instantiate`, etc.) symbol was not imported from `hydra_zen`.

fix

Add the necessary import statement at the top of your script, e.g., `from hydra_zen import builds, zen, instantiate`.

Upgrade

Version history

0.16.0latest on PyPI · released Oct 22, 2025

Audit

Dependencies

hydra-corerequiredRequired for core configuration management and CLI integration.

pydanticoptionalOptional, enables Pydantic-powered type-checking and validation for configs.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mit-ll-responsible-ai/hydra-zen ↗

packagehttps://pypi.org/project/hydra-zen/ ↗

homepagehttps://mit-ll-responsible-ai.github.io/hydra-zen/ ↗