Hydra: Composable Configuration for Complex Apps

Why it exists

Complex apps, especially in machine learning, require managing countless configuration variations for experiments—different learning rates, model sizes, or datasets. Manually editing large config files or passing dozens of command-line flags is error-prone and creates a mess of slightly different config file versions.

The mental model

Think of configuration as a composition, not a monolith. Hydra lets you define small, self-contained config files (e.g., database/postgres.yaml, model/resnet.yaml) and then compose them into a final configuration for a specific run. It's like building with LEGOs: you pick the pieces you need and snap them together for the task at hand.

How it works

Hydra, powered by OmegaConf, parses a primary config file that can include directives to pull in other files. You structure your configs in a directory tree (e.g., conf/model/bert.yaml, conf/dataset/squad.yaml). From the command line, you can select which pieces to use (python my_app.py model=bert) and override any specific value within them (model.learning_rate=0.01). Hydra handles parsing these overrides and merging them into a single, accessible config object in your code, removing boilerplate.

When to use it

Use Hydra for projects with many moving parts and configuration axes, like ML training pipelines. It's excellent for managing experiments where you need to systematically sweep through hyperparameters or swap out entire components like models or data sources. Its pluggable architecture also allows for integrations with cloud infrastructure for launching jobs.

When not to use it

For simple applications with only a handful of static configuration values, Hydra is overkill. The added complexity of a directory structure and composition logic isn't justified if a single, simple config file or a few environment variables would suffice.

One canonical example

An ML engineer wants to test two optimizers, Adam and SGD, with three learning rates. Instead of creating six config files, they define optimizer/adam.yaml and optimizer/sgd.yaml. They can then launch all six experiments from the command line using Hydra's multi-run feature: python train.py --multirun optimizer=adam,sgd optimizer.lr=0.1,0.01,0.001. Hydra runs each combination automatically.