Getting started

Introduction

Hydra is an open-source Python framework that simplifies the development of research and other complex applications. The key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line. The name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads.

Key features:

• Hierarchical configuration composable from multiple sources
• Configuration can be specified or overridden from the command line
• Dynamic command line tab completion
• Run your application locally or launch it to run remotely
• Run multiple jobs with different arguments with a single command

Versions

Hydra supports Linux, Mac and Windows.

	Version	Docs	Release notes	Python Version
►	0.11 (Stable)	0.11 Doc	Release notes	2.7, 3.5+
	1.0 (Release candidate)	Switch to 1.0 Docs	Release notes	3.6+

Quick start guide

This guide will show you some of the most important features of Hydra. Read the tutorial to gain a deeper understanding.

Installation

Install Hydra 0.11 with pip install hydra-core --upgrade.

Basic example

Configuration file: config.yaml

db:

driver: mysql

user: omry

pass: secret

Python file: my_app.py

import hydra

from omegaconf import DictConfig

@hydra.main(config_path="config.yaml")

def my_app(cfg : DictConfig) -> None:

print(cfg.pretty())

if __name__ == "__main__":

my_app()

You can learn more about OmegaConf here later.

config.yaml is loaded automatically when you run your application

$ python my_app.py

db:

driver: mysql

pass: secret

user: omry

You can override values in the loaded config from the command line:

$ python my_app.py db.user=root db.pass=1234

db:

driver: mysql

user: root

pass: 1234

Composition example

You may want to alternate between two different databases. to support this create a config group named db, and place one config file for each alternative inside: The directory structure of our application now looks like:

├── db

│ ├── mysql.yaml

│ └── postgresql.yaml

├── config.yaml

└── my_app.py

Here is the new config.yaml

defaults:

- db: mysql

# some other config options in your config file.

website:

domain: example.com

defaults is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object. The resulting cfg object is a composition of configs from defaults with configs specified in your config.yaml.

You can now choose which database configuration to use from the and override values from the command line:

$ python my_app.py db=postgresql db.timeout=20

db:

driver: postgresql

pass: drowssap

timeout: 20

user: postgre_user

website:

domain: example.com

You can have as many config groups as you need.

Multirun

You can run your function multiple times with different configuration easily with the --multirun|-m flag.

$ python my_app.py --multirun db=mysql,postgresql

[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29

[HYDRA] Launching 2 jobs locally

[HYDRA] #0 : db=mysql

db:

driver: mysql

pass: secret

user: omry

website:

domain: example.com

[HYDRA] #1 : db=postgresql

db:

driver: postgresql

pass: drowssap

timeout: 10

user: postgre_user

website:

domain: example.com

There is a whole lot more to Hydra. Read the tutorial to learn more.

Other stuff

Community

Ask questions in the chat or StackOverflow (Use the tag #fb-hydra):

• Zulip Chat
• StackOverflow

Follow Hydra on Twitter and Facebook:

• Facebook page
• Twitter

Citing Hydra

If you use Hydra in your research please use the following BibTeX entry:

@Misc{,

author = {Omry Yadan},

title = {A framework for elegantly configuring complex applications},

howpublished = {Github},

year = {2019},

url = {https://github.com/facebookresearch/hydra}

}