Skip to main content
Version: Next

Selecting default configs

Β Example (Click Here)

After office politics, you decide that you want to use MySQL by default. You no longer want to type +db=mysql every time you run your application.

You can add a Default List to your config file. A Defaults List is a list telling Hydra how to compose the final config object. By convention, it is the first item in the config.

Config group defaults​

config.yaml
defaults:
- db: mysql

Remember to specify the config_name:

from omegaconf import DictConfig, OmegaConf
import hydra

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

if __name__ == "__main__":
my_app()

When you run the updated application, MySQL is loaded by default.

$ python my_app.py
db:
driver: mysql
pass: secret
user: omry

You can have multiple items in the defaults list, e.g.

defaults:
- db: mysql
- db/mysql/engine: innodb

The defaults are 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.

Overriding a config group default​

You can still load PostgreSQL, and override individual values.

$ python my_app.py db=postgresql db.timeout=20
db:
driver: postgresql
pass: drowssap
timeout: 20
user: postgres_user

You can remove a default entry from the defaults list by prefixing it with ~:

$ python my_app.py ~db
{}

Composition order of primary config​

Your primary config can contain both config values and a Defaults List. In such cases, you should add the _self_ keyword to your defaults list to specify the composition order of the config file relative to the items in the defaults list.

  • If you want your primary config to override the values of configs from the Defaults List, append _self_ to the end of the Defaults List.
  • If you want the configs from the Defaults List to override the values in your primary config, insert _self_ as the first item in your Defaults List.
config.yaml
defaults:
- db: mysql
- _self_

db:
user: root
Result config: db.user from config.yaml
db:
driver: mysql # db/mysql.yaml
pass: secret # db/mysql.yaml
user: root # config.yaml


config.yaml
defaults:
- _self_
- db: mysql

db:
user: root
Result config: All values from db/mysql
db:
driver: mysql # db/mysql.yaml
pass: secret # db/mysql.yaml
user: omry # db/mysql.yaml


See Composition Order for more information.

info

The default composition order changed between Hydra 1.0 and Hydra 1.1.

  • Hydra 1.0: Configs from the defaults list are overriding the primary config
  • Hydra 1.1: A config is overriding the configs from the defaults list.

To mitigate confusion, Hydra 1.1 issue a warning if the primary config contains both Default List and Config values, and _self_ is not specified in the Defaults List.
The warning will disappear if you add _self_ to the Defaults List based on the desired behavior.

Non-config group defaults​

Sometimes a config file does not belong in any config group. You can still load it by default. Here is an example for some_file.yaml.

defaults:
- some_file

Config files that are not part of a config group will always be loaded. They cannot be overridden.
Prefer using a config group.

info

For more information about the Defaults List see Reference Manual/The Defaults List.