Skip to main content
Version: Next

Terminology

This page describes some common concepts in Hydra, most of which are covered in greater details throughout the documentation. Examples of many of the following concepts are in the Examples section.

Input Configs​

Input configs are building blocks used to construct the Output Config consumed by the application. They can be grouped by placing them in Config Groups.

Config files​

Config files are form of input configs in YAML format. They can exist in the file system or in a Python module.

Example config file
user:
  name: James Bond
  age: 7

Structured Config​

This term has two common meanings:

  1. A class decorated with @dataclass or @attr.s, or an instance of such a class which is intended to be used as config.
  2. A Config object initialized from a class or object as defined in 1. Structured Configs provide additional type information that enables static and runtime type checking.

The two primary patterns for using Structured Configs are:

  • As an Input Config.
  • As a schema validating Config Files and command line arguments.
Example Schema
@dataclass
class User:
  name: str
  age: int

Other configs​

Primary Config: The input config named in @hydra.main() or in the Compose API.
Output Config: A config composed from the Input Configs and Overrides by @hydra.main(), or the Compose API.

Overrides​

Overrides are strings that can be used to manipulate the config composition process. This includes updating, adding and deleting config values and Defaults List options.

Overrides can be used in the command line and in the Compose API.
In the examples below, key=value is an override:

Override in the command line
$ python my_app.py key=value

Override used in the Compose API
cfg = compose(config_name, 
              overrides=["key=value"])

Defaults List​

A list in an Input Config that instructs Hydra how compose the config.

Defaults List in a YAML config
defaults:
  - db: mysql      # An overridable defaults list entry
  - schema/school  # A non-overridable defaults list entry

Config Group​

A Config Group is a directory in the Config Search Path that contains Input Configs. Config Groups can be nested, and in that case the path elements are separated by a forward slash ('/') regardless of the operating system.

Config Group Option​

An Input Config in a Config Group. When used in a Defaults List, a Config Group Option can be a single Input Config, or a list of Input Configs from the same Config Group.

Package​

A Package is the path to node in a config. By default, the Package of a Config Group Option is derived from the Config Group. e.g: Configs in mi6/agent will have the package mi6.agent by default.

The Package Directive specifies the root Package of a Config File. It can appear at the top of YAML config file.

Example of Core Concepts​

config.yaml
defaults:
 - mi6/agent: james_bond

mi6/agent/james_bond.yaml
# @package bond.james
codename: '007'

Output config
bond:
  james:
    codename: '007'

Config Search Path​

The Config Search Path is a list of paths that are searched in order to find configs. It is similar to the Python PYTHONPATH.

Plugins​

Plugins extend Hydra's capabilities. Hydra has several plugin types, for example Launcher and Sweeper.