Version: 1.0

Basic Override syntax

You can manipulate your configuration with overrides (via the command line or the Compose API). This includes:

  • Modifying the the Defaults List
  • Modifying the config object

Overrides matching a config group are modifying the Defaults List; The rest are manipulating the config object.

Basic examples

Modifying the Config Object

  • Overriding a config value :
  • Appending a config value :
  • Removing a config value :,

Modifying the Defaults List

  • Overriding selected Option: db=mysql
  • Changing a package: [email protected]_pkg:dst_pkg
  • Overriding selected Option and changing the package: [email protected]_pkg:dst_pkg=mysql
  • Appending to defaults: +db=mysql
  • Deleting from defaults: ~db, ~db=mysql


Hydra supports a rich DSL in the command line. Below are the parser rules from grammar. You can see the full grammar on GitHub (lexer and parser)

override: (
key EQUAL value? // key=value, key= (for empty value)
| TILDE key (EQUAL value?)? // ~key | ~key=value
| PLUS key EQUAL value? // +key= | +key=value
) EOF;
key :
packageOrGroup // key
| packageOrGroup AT package (COLON package)? // [email protected] | [email protected]:pkg2
| packageOrGroup ATCOLON package // [email protected]:pkg2
packageOrGroup: package | ID (SLASH ID)+; // db, hydra/launcher
package: (ID | DOT_PATH); // db, hydra.launcher
value: element | simpleChoiceSweep;
| listValue
| dictValue
| function
argName: ID EQUAL;
function: ID POPEN (argName? element (COMMA argName? element )* )? PCLOSE;
element (COMMA element)+ // value1,value2,value3
QUOTED_VALUE // 'hello world', "hello world"
| ( ID // foo_10
| NULL // null, NULL
| INT // 0, 10, -20, 1_000_000
| FLOAT // 3.14, -20.0, 1e-1, -10e3
| BOOL // true, TrUe, false, False
| INTERPOLATION // ${}, ${env:USER,me}
| UNQUOTED_CHAR // /, -, \, +, ., $, *
| COLON // :
| WS // whitespaces
listValue: BRACKET_OPEN // [], [1,2,3], [a,b,[1,2]]
(element(COMMA element)*)?
dictValue: BRACE_OPEN
(ID COLON element (COMMA ID COLON element)*)? // {}, {a:10,b:20}



Key is the component before the =. A few examples: # A config key
hydra/launcher # A config group
[email protected] # A config group assigned to the package pkg
[email protected]:pkg2 # A config group changing the package from pkg1 to pkg2

Quoted values

Hydra supports both double quotes and single quoted values. Quoted strings can accept any value between the quotes. To include a single quote in a single quoted string escape it : \'. Same for double quote in a double quoted string.

Double quotes
"hello there"
"escaped \"double quote\""
"{a:10} ${xyz}"
"'single quoted string'"
Single quotes
'hello there'
'escaped \'single quote\''
'{a:10} ${xyz}'
'"double quoted string"'

Whitespaces in unquoted values

Unquoted Override values can contain non leading or trailing whitespaces. For example, msg=hello world is a legal override (key is msg and value is the string hello world). Normally, your shell will interpret values with whitespaces as being multiple parameters (key=a b would be interpreted as key=a and b). To prevent this you can quote them with a single quote. For example:

$ python 'msg=hello world'

Note that trailing and leading whitespace are ignored, the above is equivalent to:

$ python 'msg= hello world '


  • id : oompa10, loompa_12
  • null: null
  • int: 10, -20, 0, 1_000_000.
  • float: 3.14, -10e6, inf, -inf, nan.
  • bool: true, false
  • dot_path:
  • interpolation: ${}, ${env:USER,me}

Constants (null, true, false, inf, nan) are case insensitive.

IMPORTANT Always single-quote interpolations in the shell.



IMPORTANT Always single-quote overrides that contains lists in the shell.



IMPORTANT Always single-quote overrides that contains dicts in the shell.

Sweeper syntax

A choice sweep is comma separated list with two or more elements:

key=a,b # Simple sweep: ChoiceSweep(a, b)
key="a,b","c,d" # Elements can be quoted strings, ChoiceSweep("a,b", "c,d")
key=[a,b],[c,d] # Elements can be real lists, ChoiceSweep([a,b], [c,d])
key={a:10, b:20},{c:30,d:40} # And dictionaries: ChoiceSweep({a:10, b:20}, {c:30,d:40})

More sweeping options are described in the Extended Grammar page.

IMPORTANT You may need to quote your choice sweep in the shell


Hydra supports several functions in the command line. See the Extended Grammar page for more information.

Working with your shell

All shells interprets command line inputs and may change what is passed to the process. A good way to determine what the shell is doing to your command is to echo it.

# bash output
$ echo foo_{a:10,b:20} ${HOME} [b,c]*
foo_a:10 foo_b:20 /home/omry build_helpers
$ echo 'foo_{a:10,b:20}' '${HOME}' '[b,c]*'
foo_{a:10,b:20} ${HOME} [b,c]*

If in doubt, quote a command line element with a single quote (').

If you want to pass quotes to Hydra in a shell quoted string, it's best to pass double quotes.

$ echo '"hello world"'
"hello world"

You can use some shell specific commands to change their behavior, but the cost will be that their behavior will change.


You can disable braces expansion, filename generation (globing) and hist expansion. Please note that this will change your shell behavior for the current session.

$ set +o braceexpand -o noglob +o histexpand
$ echo key1={a:10,b:20} key2=${HOME} key=[b]*
key1={a:10,b:20} key2=/home/omry key=[b]*
# does not help with () though:
$ echo key=choice(a,b,c)
bash: syntax error near unexpected token '('
$ echo 'key=choice(a,b,c)'

Other shells

Send a PR to add information about your favorite shell here.

Last updated on by Omry Yadan