Skip to main content
Version: Next

Apply command-line overrides

OmegaConf.from_dotlist() parses key=value strings. It builds nested containers from dotted paths and parses values as YAML. Merge the resulting config after your defaults so it wins on conflicts:

>>> from omegaconf import OmegaConf
>>> defaults = OmegaConf.create({
... "server": {"port": 80},
... "debug": False,
... })
>>> overrides = OmegaConf.from_dotlist(["server.port=8080", "debug=true"])
>>> cfg = OmegaConf.merge(defaults, overrides)
>>> cfg.server.port, cfg.debug
(8080, True)

OmegaConf.from_cli() reads the same format from the command-line arguments in sys.argv[1:]. Call it without arguments in an application that receives OmegaConf overrides directly. An argument parser may collect the strings and pass them to from_dotlist() instead.

Malformed key paths raise GrammarParseError. All paths in a dotlist are checked before any entry is applied, including when using cfg.merge_with_dotlist() or cfg.merge_with_cli(). Other errors, such as a value failing type validation, may still leave earlier entries applied.

Backslash escapes in key paths follow the interpolation rules. For example, r"a\.b=10" addresses the key a.b, and r"a\:b=10" addresses a:b. Two backslashes encode one literal backslash. A following unescaped dot still separates parent and child keys:

>>> cfg = OmegaConf.from_dotlist([r"a\\.b=10"])
>>> cfg["a\\"]["b"]
10
>>> OmegaConf.select(cfg, r"a\\.b")
10
>>> OmegaConf.update(cfg, r"a\\.b", 20)
>>> cfg["a\\"]["b"]
20

The recognized escapes cover backslashes, dots, brackets, colons, equals signs, braces, parentheses, quotes, spaces, and tabs. Unknown escapes, such as \q, retain the backslash. Raw dictionary indexing uses literal keys.

In 2.4.1, select(), update(), and dotlists now decode the same key-segment escapes as interpolation. This changes existing spellings containing backslashes: use r"a\\\.b" for the single key a\.b, and r"a\\\:b" for the single key a\:b. The old spellings were r"a\\.b" and r"a\:b", respectively. The new spellings also work in interpolation paths.

When passing an override through a shell, quote it so the backslash reaches Python unchanged:

python app.py 'a\.b=10'