Skip to main content
Version: Next

The Defaults List

Introduction​

important

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.

Defaults List YAML syntax
defaults:
 (- CONFIG|GROUP_DEFAULT)*

CONFIG                 : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?
GROUP_DEFAULT          : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION
OPTION                 : CONFIG_NAME|CONFIG_NAMES|null

CONFIG : A config to use when creating the output config. e.g. db/mysql, db/mysql@backup.

GROUP_DEFAULT : An overridable config. e.g. db: mysql, db@backup: 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 mysql.yaml.

CONFIG_NAMES : A list of config names. e.g. [mysql, sqlite]

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.

An example​

Config directory structure
├── server
│   ├── db
│   │   ├── mysql.yaml
│   │   └── sqlite.yaml
│   └── apache.yaml
└── config.yaml

Input configs:

config.yaml
defaults:
  - server/apache

debug: false



server/apache.yaml
defaults:
  - db: mysql

name: apache



server/db/mysql.yaml
name: mysql
server/db/sqlite.yaml
name: sqlite

Output config:

$ python my_app.py
server:
  db:
    name: mysql
  name: apache
debug: false

Overriding Config Group options​

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:

config.yaml
defaults:
  - server/apache
  - override server/db: sqlite

debug: false
$ python my_app.py
server:
  db:
    name: sqlite
  name: apache
debug: false

A Config Group's option can also be overridden via the command line. e.g: 

$ python my_app.py server/db=sqlite

Composition order​

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.

config.yaml
defaults:
  - db: mysql  

db:
  host: backup
Result: db.host from config
db:
  driver: mysql    # db/mysql.yaml
  host: backup     # config.yaml
  port: 3306       # db/mysql.yaml

The _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.

config.yaml
defaults:
  - _self_
  - db: mysql # Overrides this config 

db:
  host: backup
Result: All values from db/mysql
db:
  driver: mysql    # db/mysql.yaml
  host: localhost  # db/mysql.yaml
  port: 3306       # db/mysql.yaml


With _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.

Interpolation in the Defaults List​

Config Group Options can be selected using interpolation.

defaults:
  - server: apache
  - db: mysql
  - combination_specific_config: ${server}_${db}  # apache_mysql

Interpolation keys can be config groups with any @package overrides.
For example: ${db/engine}, ${db@backup}

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.

Restrictions:​

  • Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist).
  • Defaults List interpolation keys are absolute (even in nested configs).
  • The subtree expanded by an Interpolated Config may not contain Default List overrides.

See Patterns/Specializing Configs for more information.

Debugging the Defaults List​

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-tree shows the Defaults Tree.
  • --info defaults Shows the Final Defaults List.
  • --cfg job|hydra|all Shows the Output Config.

Example outputs:

python my_app.py --info defaults-tree
""
<root>:
  hydra/config:
    hydra/hydra_logging: default
    hydra/job_logging: default
    hydra/launcher: basic
    hydra/sweeper: basic
    hydra/output: default
    hydra/help: default
    hydra/hydra_help: default
    _self_
  config:
    server/apache:
      server/db: mysql
      _self_
    _self_
python my_app.py --info defaults
Defaults List
*************
| Config path                 | Package             | _self_ | Parent        | 
-------------------------------------------------------------------------------
| hydra/hydra_logging/default | hydra.hydra_logging | False  | hydra/config  |
| hydra/job_logging/default   | hydra.job_logging   | False  | hydra/config  |
| hydra/launcher/basic        | hydra.launcher      | False  | hydra/config  |
| hydra/sweeper/basic         | hydra.sweeper       | False  | hydra/config  |
| hydra/output/default        | hydra               | False  | hydra/config  |
| hydra/help/default          | hydra.help          | False  | hydra/config  |
| hydra/hydra_help/default    | hydra.hydra_help    | False  | hydra/config  |
| hydra/config                | hydra               | True   | <root>        |
| server/db/mysql             | server.db           | False  | server/apache |
| server/apache               | server              | True   | config        |
| config                      |                     | True   | <root>        |
-------------------------------------------------------------------------------
python my_app.py --cfg job
server:
  db:
    name: mysql
  name: apache
debug: false