Skip to main content
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

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 Jasha10