Many of the features described in this page are new to Hydra 1.1 and are considered experimental. Please report any issues.
A Defaults List determines how to build a config object from other configs, and in what order. Each config can have a Defaults List as a top level element. The Defaults List itself is not a part of resulting config.
The most common items in the Default List are Config Group Defaults, which determines which config group option to use from a particular config group.
Sometimes a config file should be loaded unconditionally. Such configs can be specified as a string in the Defaults List:
Config files loaded this way are not a part of a config group and will always be loaded. They cannot be overridden. In general it is recommended to use the first form (config group default) when possible.
Defaults list resolution
When composing the Output Config Object, Hydra will first create the final Defaults List and will then compose the config with it.
Creating the final defaults list is a complex process: Configs mentioned in the list may have their own defaults list, sometimes defining the same config groups!
The behavior that process is implementing can be described by two simple rules:
- The last appearance of a config group determines the final value for that group
- First appearance of a config group determines the composition order for that group
The first rule allows you to always override a config group selection that was made earlier. The second rules ensures that composition order is respected.
Composition order and
A config can contain both a Defaults List and config nodes.
The special element
_self_ can be added to determine the composition order of this config relative to the items
in the defaults list.
_self_ is not specified, it is implicitly inserted at the top of the defaults list.
This means that by default, elements in the defaults list are composed after the config declaring the Defaults List.
An example with two config files:
config.yaml, the resulting defaults list will be:
The last two items are added as a result of the expansion of
The Defaults List supports a limited form of interpolation that differs from the normal interpolation in several aspects.
- The Defaults List is resolved before the config is computed, so it cannot refer to nodes from the computed config.
- The defaults list can interpolate with config groups directly
See Specializing Configs for a more detailed explanation of this example.
Packages of previously defined config groups can be overridden by later items in the Defaults List. The syntax is similar to that described in Basic Override syntax,
Deleting from the defaults list
Previously defined config groups can be deleted by later items in the Defaults List. The syntax is similar to that described in Basic Override syntax,
Config "Inheritance" via composition
TODO: should probably not be here
A common pattern is to "extend" a base config:
In the above example,
bond.yaml is overriding the name and age in
The resulting config will thus be: