@hydra.main()

@hydra.main() is the usual entry point for a Hydra application. It composes a config, applies command-line overrides, and calls your function with the resulting DictConfig. Hydra also manages features such as multirun, logging, and the working directory.

Code example

import hydra
from omegaconf import DictConfig


@hydra.main(config_path="conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    print(cfg)


if __name__ == "__main__":
    my_app()

Calling my_app() runs Hydra's command-line entry point. For example, python my_app.py db=mysql composes conf/config.yaml, applies the db=mysql override, and passes the resulting config to the function. See the tutorial for a first application.

API Documentation

@hydra.main()

def main(
    config_path: Optional[str] = None,
    config_name: Optional[str] = None,
    version_base: Optional[str] = ...,
    execution_whitelist: ExecutionWhitelist = None,
) -> Callable[[TaskFunction], Any]:
    ...

• config_path adds a directory or package to the Config Search Path. A relative directory is resolved from the Python file declaring @hydra.main(); an absolute directory is used as-is. A pkg:// path names an importable Python package. When omitted, no application directory is added.
• config_name names the primary config to compose, usually without its .yaml extension. It is resolved within the Config Search Path. When omitted, Hydra starts with an empty application config, which can still receive overrides.
• version_base is deprecated in Hydra 1.4. Omit it in new code; see the 1.4 preparation guide when upgrading an existing application.
• execution_whitelist specifies trusted targets allowed for instantiation and Python logging configured by Hydra. See Execution whitelist for its syntax and security model.

The command-line flags --config-path and --config-name can override the corresponding decorator parameters. See Hydra command-line flags.

Return value

For a normal my_app() call, the decorated function returns None, even if the task function returns a value. A multirun may call the task function multiple times, so there is no single task value to return. The task's result is available to Hydra's job execution machinery, not as the return value of my_app(). A hyperparameter optimization (HPO) sweeper can use each job's return value to evaluate a trial.

For example, with x and y defined in conf/config.yaml, an HPO sweeper can be configured to vary them and minimize the value returned by this function:

import hydra
from omegaconf import DictConfig


@hydra.main(config_path="conf", config_name="config")
def objective(cfg: DictConfig) -> float:
    return float(cfg.x**2 + cfg.y**2)


if __name__ == "__main__":
    objective()

See the Optuna Sweeper for a complete example.

Config passthrough

You can pass a DictConfig directly to the decorated function:

from omegaconf import OmegaConf

cfg = OmegaConf.create({"db": "mysql"})
my_app(cfg)

In this form, Hydra passes cfg directly to the task function and returns its value. It does not parse command-line arguments, compose a config, or run Hydra's job machinery. This is useful when a caller has already prepared a config, such as in a test; it is not equivalent to a normal Hydra application run.

For composing configs programmatically without using the decorator as an entry point, see the Compose API. For wrapping a Hydra entry point with other decorators, see Decorating the main function.