Default composition order is changing in Hydra 1.1.
For this example, let's assume the following two configs:
- foo: bar
# @package _group_
In Hydra 1.0, configs from the Defaults List are overriding config.yaml, resulting in the following output:
As of Hydra 1.1, config.yaml is overriding configs from the Defaults List, resulting in the following output:
If your application uses
hydra.main, the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of
python my_app.py --cfg job on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration.
Primary config is a YAML file
To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing
_self_, and there are config values in addition to the Defaults List.
To address the warning, add
_self_ to the Defaults List of the primary config.
- If the new behavior works for your application, append
_self_to the end of the Defaults List.
- If your application requires the previous behavior, insert
_self_as the first item in your Defaults List.
- foo: bar
The Defaults List is described here.
Primary config is a Structured Config
Structured Configs used as primary config may see changes as well.
You should add
_self_ to the defaults list to indicate the composition order. In such cases you will typically want
_self_ to be the first item in the defaults list.
defaults = [
# this is unfortunately verbose due to @dataclass limitations
defaults: List[Any] = field(default_factory=lambda: defaults)
# Hydra will populate this field based on the defaults list
db: Any = MISSING
Primary config is a config file with a Structured Config schema
If you use Structured Config as a schema for your primary config, be sure to add
_self_ after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around.
host: str = "localhost"
port: int = 8080
- base_config # schema
- _self_ # after schema
host: localhost # schema
port: 3306 # config.yaml
Compatibility with both Hydra 1.0 and 1.1
If your config must be compatible with both Hydra 1.0 and 1.1, Insert
_self_ as the first item in the Defaults List.
Hydra 1.0.7 (or newer releases in Hydra 1.0) ignores
_self_ in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if
_self_ is the first item.