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:
 - [email protected]: mysql
 - [email protected]: mysql




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.