Many of the features described in this page are new. Please report any issues.
The Defaults List is a list in an input config that instructs Hydra how to build the output config. Each input config can have a Defaults List as a top level element. The Defaults List itself is not a part of output config.
CONFIG : A config to use when creating the output config. e.g.
GROUP_DEFAULT : An overridable config. e.g.
[email protected]: mysql.
- override : Overrides the option of a previously defined GROUP_DEFAULT.
- optional : By default, an OPTION that do not exist causes an error; optional suppresses the error.
- null : A place-holder for a future override. If it is not overridden the entry is ignored.
CONFIG_NAME: The name of a config, without the file system extension. e.g.
mysql and not
CONFIG_NAMES : A list of config names. e.g.
CONFIG_GROUP : A path to a set of configs.
The path is relative to the containing config. It can be made absolute by prefixing it with a
The path separator is
/ regardless of the operating system.
OPTION: The currently selected CONFIG_NAME or CONFIG_NAMES from a CONFIG_GROUP.
PACKAGE : Where to place the content of the config within the output config. It is relative to the Package of the containing config by default. See Packages.
A Config Group's option can be overridden using a new GROUP_DEFAULT with the override keyword. If a Group Default is overridden more than once, the last one, in depth first order, wins.
Extending the previous example:
A Config Group's option can also be overridden via the command line. e.g:
The Defaults List is ordered:
- If multiple configs define the same value, the last one wins.
- If multiple configs contribute to the same dictionary, the result is the combined dictionary.
By default, the content of a config is overriding the content of configs in the defaults list.
_self_ entry determines the relative position of this config in the Defaults List.
If it is not specified, it is added automatically as the last item.
_self_ at the top of the Defaults List, the host field defined in config.yaml now precedes the host field defined
in db/mysql.yaml, and as a result is overridden.
Config Group Options can be selected using interpolation.
Interpolation keys can be config groups with any @package overrides.
The selected option for combination_specific_config depends on the final selected options for db and server.
e.g. If db is overridden to sqlite, combination_specific_config will become apache_sqlite.
- Defaults List interpolation is only supported in the primary config.
- The subtree expanded by an Interpolated Config may not contain overrides.
- Interpolation Keys in the Defaults List cannot reference values in the Final Config Object (it does not yet).
See Patterns/Specializing Configs for more information.
Hydra's config composition process is as follows:
- The Defaults Tree is created.
- The Final Defaults List is created via a DFS walk of the Defaults Tree.
- The Output Config is composed from the entries in the Final Defaults List.
You can inspect these artifacts via command line flags:
--info defaults-treeshows the Defaults Tree.
--info defaultsShows the Final Defaults List.
--cfg job|hydra|allShows the Output Config.