Version: 1.0

Overriding packages

Example application

The contents of a config file can be relocated, or replicated, within the config, via package overrides.

Package specification

Definition of a package
PACKAGE : _global_ | COMPONENT[.COMPONENT]*
COMPONENT : _group_ | _name_ | \w+
_global_ : the top level package (equivalent to the empty string).
_group_ : the config group in dot notation: foo/bar/zoo.yaml -> foo.bar
_name_ : the config file name: foo/bar/zoo.yaml -> zoo

Overriding the package in a file via a package directive

A @package directive specifies a common package for all nodes in the config file. It must be placed at the top of each config group file.

Package directive examples
# @package foo.bar
# @package _global_
# @package _group_
# @package _group_._name_
# @package foo._group_._name_

Examples

A package directive with a literal
mysql.yaml
# @package foo.bar
db:
host: localhost
port: 3306
Interpretation
foo:
bar:
db:
host: localhost
port: 3306
A package directive with _group_ and _name_
db/mysql.yaml
# @package _group_._name_
host: localhost
port: 3306
Interpretation
db:
mysql:
host: localhost
port: 3306

Overriding the package via the defaults list

The following example adds the mysql config in the packages db.src and db.dst.

config.yaml
defaults:
Interpretation
db:
src:
host: localhost
port: 3306
dst:
host: localhost
port: 3306

Overriding the package via the command line

Overriding the package for db specified in the defaults list from db.dst to backup:

# Change the package
$ python my_app.py [email protected]:backup
# Change both the package and config group option
$ python my_app.py [email protected]:backup=postgresql

Overriding the package of a config group option not in the defaults list:

python my_app.py [email protected]=apache

For more details, see the Command line overrides page.

History and future of the package directive

The primary config, named in @hydra.main() should not have a package directive.

For config files in config groups the default depends on the version:

  • In Hydra 0.11, there was an implicit default of _global_
  • Hydra 1.0 the default is _global_
    A warning is issued for each config group file without a @package directive.
  • In Hydra 1.1 the default for config group files will become _group_

By adding an explicit @package to your configs files, you guarantee that they
will not break when you upgrade to Hydra 1.1.

Last updated on by Omry Yadan