Skip to main content
Version: Next

Defaults List


You can define a defaults list in your primary Structured Config just like you can in your primary config.yaml file. The example below extends the previous example by adding a defaults list that will load db=mysql by default.

from omegaconf import MISSING, OmegaConf
@dataclassclass MySQLConfig:    ...
@dataclassclass PostGreSQLConfig:    ...
defaults = [    # Load the config "mysql" from the config group "db"    {"db": "mysql"}]
@dataclassclass Config:    # 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
cs = ConfigStore.instance()"db", name="mysql", node=MySQLConfig)"db", name="postgresql", node=PostGreSQLConfig)"config", node=Config)

@hydra.main(config_path=None, config_name="config")def my_app(cfg: Config) -> None:    print(OmegaConf.to_yaml(cfg))

if __name__ == "__main__":    my_app()

Running loads the mysql config option by default:

$ python my_app.pydb:  driver: mysql  ...

You can override the default option via the command line:

$ python db=postgresqldb:  driver: postgresql  ...

A Note about composition order#

The default composition order in Hydra is that values defined in a config are merged into values introduced from configs in the Defaults List - or in other words - overriding them. This behavior can be unintuitive when your primary config is a Structured Config, like in the example above. For example, if the primary config is:

@dataclassclass Config:    defaults: List[Any] = field(default_factory=lambda:  [        "debug/activate",        # If you do not specify _self_, it will be appended to the end of the defaults list by default.        "_self_"    ])
    debug: bool = False

And debug/activate.yaml is overriding the debug flag to True, the composition order would be such that debug ends up being False.
To get debug/activate.yaml to override this config, explicitly specify _self_ before debug/activate.yaml:

@dataclassclass Config:    defaults: List[Any] = field(default_factory=lambda:  [        "_self_",        "debug/activate",    ])
    debug: bool = False

See Composition Order for more information.

Requiring users to specify a default list value#

Set db as MISSING to require the user to specify a value on the command line.

Defaults list with a missing db
defaults = [    {"db": MISSING}]

$ python my_app.pyYou must specify 'db', e.g, db=<OPTION>Available options:        mysql        postgresql