Usage

Installation

Just pip install:

pip install omegaconf

OmegaConf requires Python 3.8 or newer.

Creating

You can create OmegaConf objects from multiple sources.

Empty

>>> from omegaconf import OmegaConf
>>> conf = OmegaConf.create()
>>> print(OmegaConf.to_yaml(conf))
{}

From a dictionary

>>> conf = OmegaConf.create({"k" : "v", "list" : [1, {"a": "1", "b": "2", 3: "c"}]})
>>> print(OmegaConf.to_yaml(conf))
k: v
list:
- 1
- a: '1'
  b: '2'
  3: c

Here is an example of various supported key types:

>>> from enum import Enum
>>> class Color(Enum):
...   RED = 1
...   BLUE = 2
>>>
>>> conf = OmegaConf.create(
...   {"key": "str", 123: "int", True: "bool", 3.14: "float", Color.RED: "Color", b"123": "bytes"}
... )
>>>
>>> print(conf)
{'key': 'str', 123: 'int', True: 'bool', 3.14: 'float', <Color.RED: 1>: 'Color', b'123': 'bytes'}

OmegaConf supports str, int, bool, float bytes, and Enum as dictionary key types.

From a list

>>> conf = OmegaConf.create([1, {"a":10, "b": {"a":10, 123: "int_key"}}])
>>> print(OmegaConf.to_yaml(conf))
- 1
- a: 10
  b:
    a: 10
    123: int_key

Tuples are supported as a valid option too.

From a YAML file

>>> conf = OmegaConf.load('source/example.yaml')
>>> # Output is identical to the YAML file
>>> print(OmegaConf.to_yaml(conf))
server:
  port: 80
log:
  file: ???
  rotation: 3600
users:
- user1
- user2

From a YAML string

>>> s = """
... a: b
... b: c
... list:
... - item1
... - item2
... 123: 456
... """
>>> conf = OmegaConf.create(s)
>>> print(OmegaConf.to_yaml(conf))
a: b
b: c
list:
- item1
- item2
123: 456

From a dot-list

Each entry is a "key=value" string. The key path uses dot/bracket notation. Keys that contain literal dots, brackets, or = can be escaped with a backslash (see Key path escaping).

>>> dot_list = ["a.aa.aaa=1", "a.aa.bbb=2", "a.bb.aaa=3", "a.bb.bbb=4"]
>>> conf = OmegaConf.from_dotlist(dot_list)
>>> print(OmegaConf.to_yaml(conf))
a:
  aa:
    aaa: 1
    bbb: 2
  bb:
    aaa: 3
    bbb: 4

From command line arguments

To parse the content of sys.arg:

>>> # Simulating command line arguments
>>> sys.argv = ['your-program.py', 'server.port=82', 'log.file=log2.txt']
>>> conf = OmegaConf.from_cli()
>>> print(OmegaConf.to_yaml(conf))
server:
  port: 82
log:
  file: log2.txt

From structured config

You can create OmegaConf objects from structured config classes or objects. This provides static and runtime type safety. See Structured Configs for more details, or keep reading for a minimal example.

>>> from dataclasses import dataclass
>>> @dataclass
... class MyConfig:
...     port: int = 80
...     host: str = "localhost"
>>> # For strict typing purposes, prefer OmegaConf.structured() when creating structured configs
>>> conf = OmegaConf.structured(MyConfig)
>>> print(OmegaConf.to_yaml(conf))
port: 80
host: localhost

You can use an object to initialize the config as well:

>>> conf = OmegaConf.structured(MyConfig(port=443))
>>> print(OmegaConf.to_yaml(conf))
port: 443
host: localhost

OmegaConf objects constructed from Structured classes provide runtime type safety:

>>> conf.port = 42      # Ok, type matches
>>> conf.port = "1080"  # Ok! "1080" can be converted to an int
>>> conf.port = "oops"  # "oops" cannot be converted to an int
Traceback (most recent call last):
...
omegaconf.errors.ValidationError: Value 'oops' could not be converted to Integer

In addition, the config class can be used as type annotation for static type checkers or IDEs:

>>> def foo(conf: MyConfig):
...     print(conf.port) # passes static type checker
...     print(conf.pork) # fails static type checker

Access and manipulation

Input YAML file for this section:

server:
  port: 80
log:
  file: ???
  rotation: 3600
users:
  - user1
  - user2

Access

>>> # object style access of dictionary elements
>>> conf.server.port
80

>>> # dictionary style access
>>> conf['log']['rotation']
3600

>>> # items in list
>>> conf.users[0]
'user1'

Default values

You can provide default values directly in the accessing code:

>>> conf.get('missing_key', 'a default value')
'a default value'

Mandatory values

Use the value "???" to indicate parameters that need to be set prior to access

>>> conf.log.file
Traceback (most recent call last):
...
omegaconf.MissingMandatoryValue: log.file

Manipulation

>>> # Changing existing keys
>>> conf.server.port = 81

>>> # Adding new keys
>>> conf.server.hostname = "localhost"

>>> # Adding a new dictionary
>>> conf.database = {'hostname': 'database01', 'port': 3306}

Serialization

OmegaConf objects can be saved and loaded with OmegaConf.save() and OmegaConf.load(). The created file is in YAML format. Save and load can operate on file-names, Paths and file objects.

YAML flow style

OmegaConf.to_yaml() accepts PyYAML’s default_flow_style option. For example, default_flow_style=None can keep nested collections compact:

>>> conf = OmegaConf.create({"nhood": [[-1, 0, 0], [0, -1, 0], [0, 0, -1]]})
>>> print(OmegaConf.to_yaml(conf, default_flow_style=None), end="")
nhood:
- [-1, 0, 0]
- [0, -1, 0]
- [0, 0, -1]

Save/Load YAML file

>>> conf = OmegaConf.create({"foo": 10, "bar": 20, 123: 456})
>>> with tempfile.NamedTemporaryFile() as fp:
...     OmegaConf.save(config=conf, f=fp.name)
...     loaded = OmegaConf.load(fp.name)
...     assert conf == loaded

Note that this does not retain type information.

Save/Load pickle file

Use pickle to save and load while retaining the type information. Note that the saved file may be incompatible across different versions of OmegaConf.

>>> conf = OmegaConf.create({"foo": 10, "bar": 20, 123: 456})
>>> with tempfile.TemporaryFile() as fp:
...     pickle.dump(conf, fp)
...     fp.flush()
...     assert fp.seek(0) == 0
...     loaded = pickle.load(fp)
...     assert conf == loaded

Variable interpolation

OmegaConf supports variable interpolation. Interpolations are evaluated lazily on access.

Config node interpolation

The interpolated variable can be the path to another node in the configuration, and in that case the value will be the value of that node. This path may use either dot-notation (foo.1), brackets ([foo][1]) or a mix of both (foo[1], [foo].1).

Interpolations are absolute by default. Relative interpolation are prefixed by one or more dots: The first dot denotes the level of the node itself and additional dots are going up the parent hierarchy. e.g. ${..foo} points to the foo sibling of the parent of the current node.

NOTE: Interpolations may cause config cycles. Such cycles are forbidden and may cause undefined behavior.

Input YAML file:

server:
  host: localhost
  port: 80

client:
  url: http://${server.host}:${server.port}/
  server_port: ${server.port}
  # relative interpolation
  description: Client of ${.url}

Example:

>>> conf = OmegaConf.load('source/config_interpolation.yaml')
>>> def show(x):
...     print(f"type: {type(x).__name__}, value: {repr(x)}")
>>> # Primitive interpolation types are inherited from the reference
>>> show(conf.client.server_port)
type: int, value: 80
>>> # String interpolations concatenate fragments into a string
>>> show(conf.client.url)
type: str, value: 'http://localhost:80/'
>>> # Relative interpolation example
>>> show(conf.client.description)
type: str, value: 'Client of http://localhost:80/'

Nested interpolation

Interpolations may be nested, enabling more advanced behavior like dynamically selecting a sub-config:

>>> cfg = OmegaConf.create(
...    {
...        "plans": {
...            "A": "plan A",
...            "B": "plan B",
...        },
...        "selected_plan": "A",
...        "plan": "${plans[${selected_plan}]}",
...    }
... )
>>> cfg.plan # default plan
'plan A'
>>> cfg.selected_plan = "B"
>>> cfg.plan # new plan
'plan B'

Interpolated nodes can be any node in the config, not just leaf nodes:

>>> cfg = OmegaConf.create(
...     {
...         "john": {"height": 180, "weight": 75},
...         "player": "${john}",
...     }
... )
>>> (cfg.player.height, cfg.player.weight)
(180, 75)

Resolvers

Add new interpolation types by registering resolvers using OmegaConf.register_new_resolver(). Such resolvers are called when the config node is accessed. The minimal example below shows its most basic usage, see Resolvers for more details.

>>> OmegaConf.register_new_resolver(
...     "add", lambda *numbers: sum(numbers)
... )
>>> c = OmegaConf.create({'total': '${add:1,2,3}'})
>>> c.total
6

Built-in resolvers

OmegaConf comes with a set of built-in custom resolvers:

• oc.create: Dynamically generating config nodes

• oc.decode: Parsing an input string using interpolation grammar

• oc.deprecated: Deprecate a key in your config

• oc.env: Accessing environment variables

• oc.select: Selecting an interpolation key, similar to interpolation but more flexible

• oc.dict.{keys,value}: Viewing the keys or the values of a dictionary as a list

Merging configurations

Merging configurations enables the creation of reusable configuration files for each logical component instead of a single config file for each variation of your task.

OmegaConf.merge()

Machine learning experiment example:

conf = OmegaConf.merge(base_cfg, model_cfg, optimizer_cfg, dataset_cfg)

Web server configuration example:

conf = OmegaConf.merge(server_cfg, plugin1_cfg, site1_cfg, site2_cfg)

The following example creates two configs from files, and one from the cli. It then combines them into a single object. Note how the port changes to 82.

example2.yaml file:

server:
  port: 80
users:
  - user1
  - user2

example3.yaml file:

log:
  file: log.txt

>>> from omegaconf import OmegaConf
>>> import sys
>>>
>>> # Simulate command line arguments
>>> sys.argv = ['program.py', 'server.port=82']
>>>
>>> base_conf = OmegaConf.load('source/example2.yaml')
>>> second_conf = OmegaConf.load('source/example3.yaml')
>>> cli_conf = OmegaConf.from_cli()
>>>
>>> # merge them all
>>> conf = OmegaConf.merge(base_conf, second_conf, cli_conf)
>>> print(OmegaConf.to_yaml(conf))
server:
  port: 82
users:
- user1
- user2
log:
  file: log.txt

By default, merge() is replacing the target list with the source list. Use list_merge_mode to control the merge behavior for lists. This Enum is defined in omegaconf.ListMergeMode and defines the following modes: * REPLACE: Replaces the target list with the new one (default) * EXTEND: Extends the target list with the new one * EXTEND_UNIQUE: Extends the target list items with items not present in it

example2.yaml file:

server:
  port: 80
users:
  - user1
  - user2

example4.yaml file:

users:
  - user3
  - user2

If you load them and merge them with list_merge_mode=ListMergeMode.EXTEND_UNIQUE you will get this:

>>> from omegaconf import OmegaConf, ListMergeMode
>>>
>>> cfg_1 = OmegaConf.load('source/example2.yaml')
>>> cfg_2 = OmegaConf.load('source/example4.yaml')
>>>
>>> mode = ListMergeMode.EXTEND_UNIQUE
>>> conf = OmegaConf.merge(cfg_1, cfg_2, list_merge_mode=mode)
>>> print(OmegaConf.to_yaml(conf))
server:
  port: 80
users:
- user1
- user2
- user3

Union operator (| and |=)

Python 3.9+ dict-style union operators are supported on DictConfig. These operators are not supported on ListConfig and will raise a TypeError.

cfg1 | cfg2 returns a new merged config (equivalent to OmegaConf.merge(cfg1, cfg2)):

>>> from omegaconf import OmegaConf
>>> cfg1 = OmegaConf.create({"a": 1, "b": 2})
>>> cfg2 = OmegaConf.create({"b": 20, "c": 3})
>>> result = cfg1 | cfg2
>>> print(result)
{'a': 1, 'b': 20, 'c': 3}
>>> print(cfg1)  # unchanged
{'a': 1, 'b': 2}

A plain dict can appear on either side:

>>> from omegaconf import OmegaConf
>>> cfg1 = OmegaConf.create({"a": 1, "b": 2})
>>> result = {"b": 20, "c": 3} | cfg1
>>> print(result)
{'b': 2, 'c': 3, 'a': 1}

cfg1 |= cfg2 merges in place (equivalent to cfg1.merge_with(cfg2)):

>>> from omegaconf import OmegaConf
>>> cfg1 = OmegaConf.create({"a": 1, "b": 2})
>>> cfg1 |= {"b": 20, "c": 3}
>>> print(cfg1)
{'a': 1, 'b': 20, 'c': 3}

OmegaConf.unsafe_merge()

OmegaConf offers a second faster function to merge config objects:

conf = OmegaConf.unsafe_merge(base_cfg, model_cfg, optimizer_cfg, dataset_cfg)

Unlike OmegaConf.merge(), unsafe_merge() is destroying the input configs and they should no longer be used after this call. The upside is that it’s substantially faster.

Configuration flags

OmegaConf support several configuration flags. Configuration flags can be set on any configuration node (Sequence or Mapping). if a configuration flag is not set it inherits the value from the parent of the node. The default value inherited from the root node is always false.

Read-only flag

A read-only configuration cannot be modified. An attempt to modify it will result in omegaconf.ReadonlyConfigError exception

>>> conf = OmegaConf.create({"a": {"b": 10}})
>>> OmegaConf.set_readonly(conf, True)
>>> conf.a.b = 20
Traceback (most recent call last):
...
omegaconf.ReadonlyConfigError: a.b

You can temporarily remove the read only flag from a config object:

>>> conf = OmegaConf.create({"a": {"b": 10}})
>>> OmegaConf.set_readonly(conf, True)
>>> with read_write(conf):
...   conf.a.b = 20
>>> conf.a.b
20

Struct flag

By default, OmegaConf dictionaries allow write access to unknown fields. If a field does not exist, writing it will create the field, and attempting to access the field before creation will raise an exception (either ConfigKeyError or ConfigAttributeError, depending on the mode of access). It’s sometime useful to change this behavior. Using OmegaConf.set_struct, it is possible to prevent the creation of fields that do not exist:

>>> conf = OmegaConf.create({"a": {"aa": 10, "bb": 20}})
>>> OmegaConf.set_struct(conf, True)
>>> conf.a.cc = 30
Traceback (most recent call last):
...
omegaconf.errors.ConfigAttributeError: Error setting cc=30 : Key 'cc' is not in struct
    full_key: a.cc
    reference_type=Any
    object_type=dict

You can temporarily remove the struct flag from a config object:

>>> from omegaconf import open_dict
>>> conf = OmegaConf.create({"a": {"aa": 10, "bb": 20}})
>>> OmegaConf.set_struct(conf, True)
>>> with open_dict(conf):
...   conf.a.cc = 30
>>> conf.a.cc
30

Utility functions

OmegaConf.to_container

OmegaConf config objects looks very similar to python dict and list, but in fact are not. Use OmegaConf.to_container(cfg: Container, resolve: bool) to convert to a primitive container. If resolve is set to True, interpolations will be resolved during conversion.

>>> conf = OmegaConf.create({"foo": "bar", "foo2": "${foo}"})
>>> assert type(conf) == DictConfig
>>> primitive = OmegaConf.to_container(conf)
>>> show(primitive)
type: dict, value: {'foo': 'bar', 'foo2': '${foo}'}
>>> resolved = OmegaConf.to_container(conf, resolve=True)
>>> show(resolved)
type: dict, value: {'foo': 'bar', 'foo2': 'bar'}

Using throw_on_missing

You can control how missing values are handled by OmegaConf.to_container() using the throw_on_missing keyword argument.

>>> conf = OmegaConf.create({"foo": "bar", "missing": "???"})
>>> has_missing = OmegaConf.to_container(conf, throw_on_missing=False)
>>> show(has_missing)
type: dict, value: {'foo': 'bar', 'missing': '???'}
>>> OmegaConf.to_container(conf, throw_on_missing=True)
Traceback (most recent call last):
...
omegaconf.errors.MissingMandatoryValue: Missing mandatory value: missing
    full_key: missing
    object_type=dict

By default, throw_on_missing=False. Setting throw_on_missing=True can be useful if you want your program to fail fast when there are missing values in the config.

Using structured_config_mode

You can customize the treatment of OmegaConf.to_container() for Structured Config nodes using the structured_config_mode option. The default, structured_config_mode=SCMode.DICT, converts Structured Config nodes to plain dict.

Using structured_config_mode=SCMode.DICT_CONFIG causes such nodes to remain as DictConfig, allowing attribute style access on the resulting node.

Using structured_config_mode=SCMode.INSTANTIATE, Structured Config nodes are converted to instances of the backing dataclass or attrs class. Note that when structured_config_mode=SCMode.INSTANTIATE, interpolations nested within a structured config node will be resolved, even if OmegaConf.to_container is called with the the keyword argument resolve=False, so that interpolations are resolved before being used to instantiate dataclass/attr class instances. Interpolations within non-structured parent nodes will be resolved (or not) as usual, according to the resolve keyword arg.

>>> from omegaconf import SCMode
>>> conf = OmegaConf.create({"structured_config": MyConfig})
>>> container = OmegaConf.to_container(conf,
...     structured_config_mode=SCMode.DICT_CONFIG)
>>> show(container)
type: dict, value: {'structured_config': {'port': 80, 'host': 'localhost'}}
>>> show(container["structured_config"])
type: DictConfig, value: {'port': 80, 'host': 'localhost'}

OmegaConf.to_object

The OmegaConf.to_object method recursively converts DictConfig and ListConfig objects into plain Python dicts and lists, with the exception that Structured Config objects are converted into instances of the backing dataclass or attr class. Interpolations in the config are always resolved by OmegaConf.to_object.

>>> container = OmegaConf.to_object(conf)
>>> show(container)
type: dict, value: {'structured_config': MyConfig(port=80, host='localhost')}
>>> show(container["structured_config"])
type: MyConfig, value: MyConfig(port=80, host='localhost')

Note that here, container["structured_config"] is actually an instance of MyConfig, whereas in the previous examples we had a dict or a DictConfig object that was duck-typed to look like an instance of MyConfig.

The call OmegaConf.to_object(conf) is equivalent to OmegaConf.to_container(conf, resolve=True, throw_on_missing=True, structured_config_mode=SCMode.INSTANTIATE).

OmegaConf.resolve

Normally interpolations are resolved lazily, at access time. OmegaConf.resolve() eagerly resolves all interpolations in the given config object in-place.

OmegaConf.resolve(cfg)

Example:

>>> cfg = OmegaConf.create({"a": 10, "b": "${a}"})
>>> show(cfg)
type: DictConfig, value: {'a': 10, 'b': '${a}'}
>>> assert cfg.a == cfg.b == 10 # lazily resolving interpolation
>>> OmegaConf.resolve(cfg)
>>> show(cfg)
type: DictConfig, value: {'a': 10, 'b': 10}

Warning

OmegaConf.resolve() works correctly for configs that use only node interpolations (${key}) with no custom resolvers. When custom resolvers are involved, results may depend on the depth-first, key insertion order traversal, because custom resolvers can do anything — they may be stateful, have side effects, or return different values on each call. No traversal strategy can account for this, so the limitation is by design. For configs that use custom resolvers, prefer accessing values lazily (the default) or use OmegaConf.to_container(cfg, resolve=True) to get a resolved plain Python container without mutating the config in place.

OmegaConf.select

OmegaConf.select() allows you to select a config node or value, using either a dot-notation or brackets to denote sub-keys. Keys containing literal dots, brackets, or = can be escaped with a backslash (see Key path escaping).

>>> cfg = OmegaConf.create({
...     "foo" : {
...         "missing" : "???",
...         "bar": {
...             "zonk" : 10,
...         }
...     }
... })
>>> assert OmegaConf.select(cfg, "foo") == {
...     "missing" : "???",
...     "bar":  {
...         "zonk" : 10,
...     }
... }
>>> assert OmegaConf.select(cfg, "foo.bar") == {
...     "zonk" : 10,
... }
>>> assert OmegaConf.select(cfg, "foo.bar.zonk") == 10    # dots
>>> assert OmegaConf.select(cfg, "foo[bar][zonk]") == 10  # brackets
>>> assert OmegaConf.select(cfg, "no_such_key", default=99) == 99
>>> assert OmegaConf.select(cfg, "foo.missing") is None
>>> assert OmegaConf.select(cfg, "foo.missing", default=99) == 99
>>> OmegaConf.select(cfg,
...     "foo.missing",
...     throw_on_missing=True
... )
Traceback (most recent call last):
...
omegaconf.errors.MissingMandatoryValue: missing node selected
    full_key: foo.missing

OmegaConf.can_select

OmegaConf.can_select() checks whether OmegaConf.select() can select a config node or value without returning a default or raising. It uses the same key path syntax and behavior flag names as OmegaConf.select() for convenience, but OmegaConf.can_select() itself does not raise for select failures. A selected None value is considered selectable.

>>> cfg = OmegaConf.create({
...     "foo": {
...         "bar": 10,
...         "none": None,
...         "missing": "???",
...     },
...     "bad": "${not_found}",
... })
>>> assert OmegaConf.can_select(cfg, "foo.bar")
>>> assert OmegaConf.can_select(cfg, "foo.none")
>>> assert not OmegaConf.can_select(cfg, "foo.missing")
>>> assert not OmegaConf.can_select(cfg, "foo.no_such_key")
>>> assert not OmegaConf.can_select(cfg, "bad")
>>> assert not OmegaConf.can_select(
...     cfg,
...     "bad",
...     throw_on_resolution_failure=False,
... )

OmegaConf.update

OmegaConf.update() allows you to update values in your config using either a dot-notation or brackets to denote sub-keys. Keys containing literal dots, brackets, or = can be escaped with a backslash (see Key path escaping).

The merge flag controls the behavior if the input is a dict or a list. If merge=True true (the default), dicts and lists are merged instead of being assigned. The force_add flag ensures that the path is created even if it will result in insertion of new values into struct nodes.

>>> cfg = OmegaConf.create({"foo" : {"bar": 10}})
>>> OmegaConf.update(cfg, "foo.bar", 20)
>>> assert cfg.foo.bar == 20
>>> # Set dictionary value (using dot notation)
>>> OmegaConf.update(cfg, "foo.bar", {"zonk" : 30}, merge=False)
>>> assert cfg.foo.bar == {"zonk" : 30}
>>> # Merge dictionary value (using bracket notation)
>>> # note that merge is True by default, so you don't really need it here.
>>> OmegaConf.update(cfg, "foo[bar]", {"oompa" : 40}, merge=True)
>>> assert cfg.foo.bar == {"zonk" : 30, "oompa" : 40}
>>> # force_add ignores nodes in struct mode or Structured Configs nodes
>>> # and updates anyway, inserting keys as needed.
>>> OmegaConf.set_struct(cfg, True)
>>> OmegaConf.update(cfg, "a.b.c.d", 10, force_add=True)
>>> assert cfg.a.b.c.d == 10

Key path escaping

OmegaConf.select, OmegaConf.update, OmegaConf.from_dotlist, and OmegaConf.from_cli all parse the key path through the same engine. YAML allows keys to contain any character, including the delimiters that OmegaConf uses in key paths (., [, ], =). Use a backslash to include these characters literally in a key name:

Escape sequence	Result character	Notes
\.	.	Dot is part of the key, not a path separator
\[	[	Open bracket is part of the key
\]	]	Close bracket is part of the key
\=	=	Useful in from_dotlist keys that contain =
\x (any other char)	\x	Passthrough: backslash + character unchanged

>>> cfg = OmegaConf.create({"a.b": 10, "x": {"a[0]": 20}})
>>> OmegaConf.select(cfg, r"a\.b")
10
>>> OmegaConf.update(cfg, r"a\.b", 99)
>>> cfg["a.b"]
99
>>> OmegaConf.select(cfg, r"x.a\[0\]")
20

For from_dotlist and from_cli, the = in the key must also be escaped so that it is not mistaken for the key/value separator:

>>> conf = OmegaConf.from_dotlist([r"a\.b\=c=42"])
>>> conf["a.b=c"]
42

Values may contain = freely — only the first unescaped = separates key from value:

>>> conf = OmegaConf.from_dotlist(["url=http://example.com?a=1&b=2"])
>>> conf.url
'http://example.com?a=1&b=2'

CLI / shell note: When arguments are passed on the command line, the shell processes them before Python sees them. A single backslash in a shell argument is typically consumed by the shell. To preserve it, either quote the argument or double the backslash:

# single-quote preserves the backslash literally
python app.py 'a\.b=1'

# or double-escape
python app.py a\\.b=1

OmegaConf.masked_copy

Creates a copy of a DictConfig that contains only specific keys.

>>> conf = OmegaConf.create({"a": {"b": 10}, "c":20})
>>> print(OmegaConf.to_yaml(conf))
a:
  b: 10
c: 20

>>> c = OmegaConf.masked_copy(conf, ["a"])
>>> print(OmegaConf.to_yaml(c))
a:
  b: 10

OmegaConf.is_missing

Tests if a value is missing ("???").

>>> cfg = OmegaConf.create({
...         "foo" : 10,
...         "bar": "???"
...     })
>>> assert not OmegaConf.is_missing(cfg, "foo")
>>> assert OmegaConf.is_missing(cfg, "bar")

OmegaConf.is_interpolation

Tests if a value is an interpolation.

>>> cfg = OmegaConf.create({
...         "foo" : 10,
...         "bar": "${foo}"
...     })
>>> assert not OmegaConf.is_interpolation(cfg, "foo")
>>> assert OmegaConf.is_interpolation(cfg, "bar")

OmegaConf.{is_config, is_dict, is_list}

OmegaConf.is_config tests whether an object is an OmegaConf object (e.g. DictConfig or ListConfig). OmegaConf.is_dict(cfg) is equivalent to isinstance(cfg, DictConfig), and OmegaConf.is_list(cfg) is equivalent to isinstance(cfg, ListConfig).

>>> # dict:
>>> d = OmegaConf.create({"foo": "bar"})
>>> assert OmegaConf.is_config(d)
>>> assert OmegaConf.is_dict(d)
>>> assert not OmegaConf.is_list(d)
>>> # list:
>>> l = OmegaConf.create([1,2,3])
>>> assert OmegaConf.is_config(l)
>>> assert OmegaConf.is_list(l)
>>> assert not OmegaConf.is_dict(l)

OmegaConf.missing_keys

OmegaConf.missing_keys(cfg) returns a set of missing keys present in the input cfg. Each missing key is represented as a str, using a dotlist style. This utility function can be used after creating a config object, after merging sources and so on, to check for missing mandatory fields and aid in creating a proper error message. Node interpolations that dereference missing values are reported as missing keys, whether they are the full value or part of a string. By default, custom resolver interpolations are skipped when collecting missing keys. Pass resolve_custom_resolvers=True to resolve custom resolvers and report them as missing if they dereference a missing value.

>>> missings = OmegaConf.missing_keys({
...     "foo": {"bar": "???"},
...     "missing": "???",
...      "list": ["a", None, "???"]
... })
>>> assert missings == {'list[2]', 'foo.bar', 'missing'}

The function raises a ValueError on input not representing a config.

Debugger integration

OmegaConf provides an optional pydevd plugin via the separate omegaconf-pydevd package, which enables a better debugging experience in PyCharm, VSCode and other PyDev.Debugger powered IDEs.

Install it with:

pip install omegaconf-pydevd

See the omegaconf-pydevd README for usage details and an example debugger demo.

The debugger extension enables OmegaConf-aware object inspection:

• providing information about interpolations.

• properly handling missing values ("???").

The plugin comes in two flavors:

• USER: Default behavior, useful when debugging your OmegaConf objects.

• DEV: Useful when debugging OmegaConf itself, shows the exact data model of OmegaConf.

The default flavor is USER. You can select which flavor to use using the environment variable OC_PYDEVD_RESOLVER, which takes the possible values USER, DEV and DISABLE.