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: localhostport: 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.