Skip to main content
Version: 1.0

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.
Use the version switcher in the top bar to switch between documentation versions.

VersionRelease notesPython Versions
1.1 (Stable)Release notes3.6 - 3.9
โ–บ1.0Release notes3.6 - 3.8
0.11Release notes2.7, 3.5 - 3.8

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#

pip install hydra-core --upgrade

Basic example#

Config:

config.yaml
db:  driver: mysql  user: omry  pass: secret

Application:

my_app.py
import hydrafrom omegaconf import DictConfig, OmegaConf
@hydra.main(config_name="config")def my_app(cfg : DictConfig) -> None:    print(OmegaConf.to_yaml(cfg))
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.pydb:  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=1234db:  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:

config.yaml
defaults:  - db: mysql

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=20db:  driver: postgresql  pass: drowssap  timeout: 20  user: postgres_userwebsite:  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=mysqldb:  driver: mysql  pass: secret  user: omrywebsite:    domain: example.com
[HYDRA]        #1 : db=postgresqldb:  driver: postgresql  pass: drowssap  timeout: 10  user: postgres_userwebsite:    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):

Follow Hydra on Twitter and Facebook:

Citing Hydra#

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

@Misc{Yadan2019Hydra,  author =       {Omry Yadan},  title =        {Hydra - A framework for elegantly configuring complex applications},  howpublished = {Github},  year =         {2019},  url =          {https://github.com/facebookresearch/hydra}}