Version: 0.11

Getting started


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


Hydra supports Linux, Mac and Windows.

VersionDocsRelease notesPython Version
1.0 (Stable)Switch to 1.0 DocsRelease notes3.6+
โ–บ0.110.11 DocRelease notes2.7, 3.5+

Quick start guide

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


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

Basic example

Configuration file: config.yaml

driver: mysql
user: omry
pass: secret

Python file:

import hydra
from omegaconf import DictConfig
def my_app(cfg : DictConfig) -> None:
if __name__ == "__main__":

You can learn more about OmegaConf here later.

config.yaml is loaded automatically when you run your application

$ python
driver: mysql
pass: secret
user: omry

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

$ python db.user=root db.pass=1234
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

Here is the new config.yaml

- db: mysql
# some other config options in your config file.

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 db=postgresql db.timeout=20
driver: postgresql
pass: drowssap
timeout: 20
user: postgre_user

You can have as many config groups as you need.


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

$ python --multirun db=mysql,postgresql
[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29
[HYDRA] Launching 2 jobs locally
[HYDRA] #0 : db=mysql
driver: mysql
pass: secret
user: omry
[HYDRA] #1 : db=postgresql
driver: postgresql
pass: drowssap
timeout: 10
user: postgre_user

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

Other stuff


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:

author = {Omry Yadan},
title = {Hydra - A framework for elegantly configuring complex applications},
howpublished = {Github},
year = {2019},
url = {}
Last updated on by Omry Yadan