Skip to main content
Version: 1.0

Grouping config files

ย Example

Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups.

A Config Group is a named group with a set of valid options.

  • The config options are mutually exclusive. Only one can be selected.
  • Selecting a non-existent config option generates an error message with the valid options.

To create a config group, create a directory. e.g. db to hold a file for each database configuration option. Since we are expecting to have multiple config groups, we will proactively move all the configuration files into a conf directory.

Directory layout
โ”œโ”€โ”€ confโ”‚ย ย  โ””โ”€โ”€ dbโ”‚ย ย      โ”œโ”€โ”€ mysql.yamlโ”‚ย ย      โ””โ”€โ”€ postgresql.yamlโ””โ”€โ”€ my_app.py
db/mysql.yaml
# @package _group_driver: mysqluser: omrypassword: secret

The config group determines the package of the config content inside the final config object.

Interpretation of db/mysql.yaml
db:  driver: mysql  user: omry  password: secret 

In Hydra 1.1 _group_ will become the default package.
For now, add # @package _group_ at the top of your config group files.
Learn more about packages directive here.

Using config groups#

Since we moved all the configs into the conf directory, we need to tell Hydra where to find them using the config_path parameter. config_path is a directory relative to my_app.py.

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

Running my_app.py without requesting a configuration will print an empty config.

$ python my_app.py{}

You can append an item a config group to the Defaults List.
The Defaults List is described on the next page.

$ python my_app.py +db=postgresqldb:  driver: postgresql  pass: drowssap  timeout: 10  user: postgres_user

Like before, you can still override individual values in the resulting config:

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

More advanced usages of config groups#

Config groups can be nested. For example the config group db/mysql/storage_engine can contain innodb.yaml and myisam.yaml. When selecting an option from a nested config group, use /:

$ python my_app.py +db=mysql +db/mysql/storage_engine=innodbdb:  driver: mysql  user: omry  password: secret   mysql:    storage_engine:      innodb_data_file_path: /var/lib/mysql/ibdata1      max_file_size: 1G

This simple example also demonstrated a very powerful feature of Hydra: You can compose your configuration object from multiple configuration groups.