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 requires Python 3.6 or newer, and it officially supports Linux, Mac and Windows.

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 the stable release with pip install hydra-core --upgrade.

You can install pre-release versions with pip install hydra-core --pre --upgrade. Those may contain nuts and bugs and might be incompatible with existing plugins.

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 google group or the chat:

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 = {A framework for elegantly configuring complex applications},
howpublished = {Github},
year = {2019},
url = {}
Last updated on by Harutaka Kawamura