Version: 2.4 (prerelease)

OmegaConf symbols

API snapshot from OmegaConf 2.4.0rc1 source. For task-based entry points, see the Python API overview.

OmegaConf module

`II`

II(interpolation: str) -> Any

Equivalent to ${interpolation}

Parameters:

interpolation (str) –

Returns:

Any – input ${node} with type Any

`MISSING`

MISSING: Any = '???'

`OmegaConf`

OmegaConf() -> None

OmegaConf primary class

`can_select`

can_select(
    cfg: Container,
    key: str,
    *,
    throw_on_resolution_failure: bool = True,
    throw_on_missing: bool = False
) -> bool

Return True if OmegaConf.select() can select a value from a config.

This uses the same key path syntax and behavior flag names as select() for convenience, but can_select() does not raise for select failures. It returns False instead of raising or returning a default when the path cannot be selected. A selected None value counts as selectable.

Parameters:

cfg (Container) – Config node to select from
key (str) – Key path to select (dot/bracket notation, backslash-escapable)
throw_on_resolution_failure (bool) – Treat an interpolation resolution error as not selectable
throw_on_missing (bool) – Treat selecting a missing key (with the value '???') as not selectable

Returns:

bool – True if the key can be selected, otherwise False.

`clear_cache`

clear_cache(conf: BaseContainer) -> None

Clear the resolver cache for conf.

Parameters:

conf (BaseContainer) – An OmegaConf container.

`clear_resolver`

clear_resolver(name: str) -> bool

Clear(remove) any resolver only if it exists.

Returns a bool: True if resolver is removed and False if not removed.

Warning: This method can remove default resolvers as well.

Parameters:

name (str) – Name of the resolver.

Returns:

bool – A bool (True if resolver is removed, False if not found before removing).

`clear_resolvers`

clear_resolvers() -> None

Clear(remove) all OmegaConf resolvers, then re-register OmegaConf's default resolvers.

`copy_cache`

copy_cache(from_config: BaseContainer, to_config: BaseContainer) -> None

Copy the resolver cache from one config to another.

Parameters:

from_config (BaseContainer) – Source container whose cache is copied.
to_config (BaseContainer) – Destination container that receives the cache copy.

`create`

create(
    obj: Any = _DEFAULT_MARKER_,
    parent: BaseContainer | None = None,
    flags: dict[str, bool] | None = None,
    *,
    max_yaml_expanded_nodes: int | None = _DEFAULT_MAX_YAML_EXPANDED_NODES
) -> DictConfig | ListConfig | TupleConfig | None

Create an OmegaConf config from obj.

obj may be a YAML string, a dict, a list or tuple, a dataclass or attrs class (type or instance), an existing DictConfig / ListConfig / TupleConfig, or None. Omitting obj (or passing {} explicitly) returns an empty DictConfig.

Parameters:

obj (Any) – Source object to build the config from.
parent (BaseContainer | None) – Optional parent node.
flags (dict[str, bool] | None) – Optional flags dict (e.g. {"readonly": True}).
max_yaml_expanded_nodes (int | None) – Maximum YAML nodes after alias expansion when obj is a YAML string. By default, OmegaConf uses the OMEGACONF_MAX_YAML_EXPANDED_NODES environment variable if set, otherwise 10_000. Explicit arguments override the environment. Pass None only for trusted input. See https://omegaconf.readthedocs.io/en/latest/yaml_aliases.html.

Returns:

DictConfig | ListConfig | TupleConfig | None – A DictConfig, ListConfig, TupleConfig, or None.

`from_cli`

from_cli(args_list: list[str] | None = None) -> DictConfig

Create a config from command-line arguments (sys.argv[1:] by default).

Each argument must be a dotlist-style string such as "foo.bar=1".

Parameters:

args_list (list[str] | None) – Explicit list of dotlist strings; defaults to sys.argv[1:].

Returns:

DictConfig – A DictConfig built from the arguments.

`from_dotlist`

from_dotlist(dotlist: list[str]) -> DictConfig

Creates a config from a list of dotlist-style strings ("key=value" pairs).

Each entry is split on the first unescaped =. Everything before it is the key path; everything after it is the value. Key paths follow the same dot/bracket syntax as :meth:select and :meth:update.

Backslash escaping in keys: Use a backslash to include a literal special character in a key name. The escapable characters are ., [, ], and =.

r"a\.b=1" — key is "a.b" (dot is part of the key)
r"a\=b=1" — key is "a=b" (= is part of the key; the second = is the key/value separator)

Values may contain = freely; only the first unescaped = separates key from value (e.g. "url=http://x?a=1" gives key url, value http://x?a=1).

CLI / shell note: When using :meth:from_cli, arguments pass through the shell before reaching Python. A single backslash in a shell argument is usually consumed by the shell, so you must double it (\\) or quote the argument ('a\.b=1') to preserve it.

Parameters:

dotlist (list[str]) – A list of dotlist-style strings, e.g. ["foo.bar=1", "baz=qux"].

Returns:

DictConfig – A DictConfig object created from the dotlist.

`get_cache`

get_cache(conf: BaseContainer) -> dict[str, Any]

Return the resolver cache for conf.

Parameters:

conf (BaseContainer) – An OmegaConf container.

Returns:

dict[str, Any] – The resolver cache dict (resolver name -> cached values).

`get_type`

get_type(obj: Any, key: str | None = None) -> type[Any] | None

Return the type of obj, or of obj[key] when key is provided.

For structured configs this is the underlying dataclass or attrs class. For plain containers it is dict, list, or tuple.

Parameters:

obj (Any) – An OmegaConf node or container.
key (str | None) – Optional key within obj to inspect.

Returns:

type[Any] | None – The Python type, or None if not determinable.

`has_resolver`

has_resolver(name: str) -> bool

Return True if a resolver with the given name is registered.

Parameters:

name (str) – Resolver name to check.

Returns:

bool – True if registered, False otherwise.

`is_config`

is_config(obj: Any) -> bool

Return True if obj is an OmegaConf container.

Parameters:

obj (Any) – Object to test.

Returns:

bool – True if obj is an OmegaConf container, False otherwise.

`is_dict`

is_dict(obj: Any) -> bool

Return True if obj is an OmegaConf DictConfig.

Parameters:

obj (Any) – Object to test.

Returns:

bool – True if obj is a DictConfig, False otherwise.

`is_interpolation`

is_interpolation(node: Any, key: int | str | None = None) -> bool

Return True if the target node is an interpolation (e.g. ${foo.bar}).

If key is provided, checks node[key]; otherwise checks node itself.

Parameters:

node (Any) – An OmegaConf node, or a container when key is given.
key (int | str | None) – Optional key within node to inspect.

Returns:

bool – True if the value is an interpolation, False otherwise.

`is_list`

is_list(obj: Any) -> bool

Return True if obj is an OmegaConf ListConfig.

Parameters:

obj (Any) – Object to test.

Returns:

bool – True if obj is a ListConfig, False otherwise.

`is_missing`

is_missing(cfg: Any, key: DictKeyType | object = _DEFAULT_MARKER_) -> bool

Return True if cfg[key] or a detached value is missing.

Parameters:

cfg (Any) – An OmegaConf container.
key (DictKeyType | object) – Optional key (str for DictConfig, int for a sequence) to check.

Returns:

bool – True if the value is missing, False otherwise.

`is_readonly`

is_readonly(conf: Node) -> bool | None

Return the effective read-only flag of conf.

Parameters:

conf (Node) – An OmegaConf node.

Returns:

bool | None – True if read-only, False if writable, None if not set (inherits from parent).

`is_sequence`

is_sequence(obj: Any) -> bool

Return True for ListConfig and TupleConfig values only.

`is_struct`

is_struct(conf: Container) -> bool | None

Return the effective struct flag of conf.

Parameters:

conf (Container) – An OmegaConf container.

Returns:

bool | None – True if struct mode is on, False if off, None if not set (inherits from parent).

`is_tuple`

is_tuple(obj: Any) -> bool

Return True if obj is an OmegaConf TupleConfig.

Native Python tuples return False.

`legacy_register_resolver`

legacy_register_resolver(name: str, resolver: Resolver) -> None

Deprecated since version 2.4. Use OmegaConf.register_resolver() instead.

`load`

load(
    file_: str | pathlib.Path | IO[Any],
    *,
    max_yaml_expanded_nodes: int | None = _DEFAULT_MAX_YAML_EXPANDED_NODES
) -> DictConfig | ListConfig

Load a YAML config from a file path or file-like object.

Parameters:

file_ (str | Path | IO[Any]) – A file path (str or pathlib.Path) or an open file object.
max_yaml_expanded_nodes (int | None) – Maximum YAML nodes after alias expansion. By default, OmegaConf uses the OMEGACONF_MAX_YAML_EXPANDED_NODES environment variable if set, otherwise 10_000. Explicit arguments override the environment. Pass None only for trusted input. See https://omegaconf.readthedocs.io/en/latest/yaml_aliases.html.

Returns:

DictConfig | ListConfig – A DictConfig or ListConfig parsed from the YAML content.

`masked_copy`

masked_copy(conf: DictConfig, keys: str | list[str]) -> DictConfig

Create a masked copy of of this config that contains a subset of the keys

Parameters:

conf (DictConfig) – DictConfig object
keys (str | list[str]) – keys to preserve in the copy

Returns:

DictConfig – The masked DictConfig object.

`merge`

merge(
    *configs: DictConfig
    | ListConfig
    | TupleConfig
    | dict[DictKeyType, Any]
    | list[Any]
    | tuple[Any, ...]
    | Any
) -> ListConfig | TupleConfig | DictConfig

Merge a list of previously created configs into a single one

Note for maintainers: changes to merge behavior should also consider whether OmegaConf.unsafe_merge() needs the same coverage.

Parameters:

configs (DictConfig | ListConfig | TupleConfig | dict[DictKeyType, Any] | list[Any] | tuple[Any, ...] | Any) – Input configs

Returns:

ListConfig | TupleConfig | DictConfig – the merged config object.

`missing_keys`

missing_keys(cfg: Any, *, resolve_custom_resolvers: bool = False) -> set[str]

Returns a set of missing keys in a dotlist style.

Node interpolations that dereference missing values are reported as missing keys, whether they are the full value or part of a string.

Parameters:

cfg (Any) – An OmegaConf.Container, or a convertible object via OmegaConf.create (dict, list, ...).
resolve_custom_resolvers (bool) – If True, custom resolver interpolations are resolved and reported as missing when they dereference missing values. If False (the default), custom resolver interpolations are not resolved and are not reported as missing keys.

Returns:

set[str] – set of strings of the missing keys.

Raises:

ValueError – On input not representing a config.

`register_new_resolver`

register_new_resolver(
    name: str,
    resolver: Resolver,
    *,
    replace: bool = False,
    use_cache: bool = False
) -> None

Deprecated since version 2.4. Use OmegaConf.register_resolver() instead.

`register_resolver`

register_resolver(
    name: str,
    resolver: Resolver,
    *,
    replace: bool = False,
    use_cache: bool = False,
    annotation_validation: Literal["off", "warn", "error"] = "warn"
) -> None

Parameters:

name (str) – Name of the resolver.
resolver (Resolver) – Callable whose arguments are provided in the interpolation, e.g., with ${foo:x,0,${y.z}} these arguments are respectively "x" (str), 0 (int) and the value of y.z.
replace (bool) – If set to False (default), then a ValueError is raised if an existing resolver has already been registered with the same name. If set to True, then the new resolver replaces the previous one. NOTE: The cache on existing config objects is not affected, use OmegaConf.clear_cache(cfg) to clear it.
use_cache (bool) – Whether the resolver's outputs should be cached. The cache is based only on the string literals representing the resolver arguments, e.g., ${foo:${bar}} will always return the same value regardless of the value of bar if the cache is enabled for foo.
annotation_validation (Literal['off', 'warn', 'error']) – Runtime policy for resolver parameter and return annotations. "off" disables validation, "warn" emits UserWarning and preserves the value, and "error" rejects registration problems with TypeError. Validation mismatches during interpolation resolution are exposed as InterpolationResolutionError. Defaults to "warn" in OmegaConf 2.4.

`resolve`

resolve(cfg: Container) -> None

Resolves all interpolations in the given config object in-place.

This function 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 — and this function has no way to account for that.

Parameters:

cfg (Container) – An OmegaConf container.

Raises:

ValueError – If the input object is not an OmegaConf container.

`save`

save(
    config: Any, f: str | pathlib.Path | IO[Any], resolve: bool = False
) -> None

Save as configuration object to a file

Parameters:

config (Any) – OmegaConf container to save.
f (str | Path | IO[Any]) – filename or file object
resolve (bool) – True to save a resolved config (defaults to False)

`select`

select(
    cfg: Container,
    key: str,
    *,
    default: Any = _DEFAULT_MARKER_,
    throw_on_resolution_failure: bool = True,
    throw_on_missing: bool = False
) -> Any

Select a value from a config using a key path.

The key path uses dot notation ("a.b.c") or bracket notation ("a[b][c]"), or a mix of both.

Keys containing special characters (., [, ], =) can be expressed by escaping them with a backslash:

r"a\.b" — selects the key "a.b" (single key with a literal dot)
r"a\[0\]" — selects the key "a[0]"
r"a\=b" — selects the key "a=b"

A backslash before any other character passes through unchanged (r"a\b" selects the key "a\\b" — a backslash followed by b).

Parameters:

cfg (Container) – Config node to select from
key (str) – Key path to select (dot/bracket notation, backslash-escapable)
default (Any) – Default value to return if key is not found
throw_on_resolution_failure (bool) – Raise an exception if an interpolation resolution error occurs, otherwise return None
throw_on_missing (bool) – Raise an exception if an attempt to select a missing key (with the value '???') is made, otherwise return None

Returns:

Any – selected value or None if not found.

`set_cache`

set_cache(conf: BaseContainer, cache: dict[str, Any]) -> None

Replace the resolver cache for conf with a deep copy of cache.

Parameters:

conf (BaseContainer) – An OmegaConf container.
cache (dict[str, Any]) – New cache dict to install (will be deep-copied).

`set_readonly`

set_readonly(conf: Node, value: bool | None) -> None

Set the read-only flag on conf.

Parameters:

conf (Node) – An OmegaConf node.
value (bool | None) – True to make read-only, False to make writable, None to inherit from the parent.

`set_struct`

set_struct(conf: Container, value: bool | None) -> None

Set the struct flag on conf.

When struct mode is enabled, accessing or setting keys that do not exist in the config raises an exception.

Parameters:

conf (Container) – An OmegaConf container.
value (bool | None) – True to enable struct mode, False to disable it, None to inherit from the parent.

`structural_equality`

structural_equality(cfg1: Any, cfg2: Any) -> bool

Compare two configs by their unresolved container structure.

Interpolations and custom resolver expressions are compared as their raw strings and are not resolved. Missing values do not raise. An escaped literal ??? is distinct from a missing value.

Parameters:

cfg1 (Any) – First OmegaConf config to compare.
cfg2 (Any) – Second OmegaConf config to compare.

Returns:

bool – True if both configs have the same unresolved structure.

`structured`

structured(
    obj: Any,
    parent: BaseContainer | None = None,
    flags: dict[str, bool] | None = None,
    *,
    max_yaml_expanded_nodes: int | None = _DEFAULT_MAX_YAML_EXPANDED_NODES
) -> Any

Alias for OmegaConf.create(obj). Accepts any input that create accepts, though intended for structured config objects (dataclass or attrs types/instances).

Parameters:

obj (Any) – Source object — typically a dataclass or attrs type or instance, but any value accepted by OmegaConf.create is valid.
parent (BaseContainer | None) – Optional parent node.
flags (dict[str, bool] | None) – Optional flags dict (e.g. {"readonly": True}).
max_yaml_expanded_nodes (int | None) – Maximum YAML nodes after alias expansion when obj is a YAML string. By default, OmegaConf uses the OMEGACONF_MAX_YAML_EXPANDED_NODES environment variable if set, otherwise 10_000. Explicit arguments override the environment. Pass None only for trusted input. See https://omegaconf.readthedocs.io/en/latest/yaml_aliases.html.

Returns:

Any – A DictConfig, ListConfig, TupleConfig, or None.

`to_container`

to_container(
    cfg: Any,
    *,
    resolve: bool = False,
    throw_on_missing: bool = False,
    enum_to_str: bool = False,
    structured_config_mode: SCMode = SCMode.DICT
) -> dict[DictKeyType, Any] | list[Any] | tuple[Any, ...] | str | Any | None

Recursively converts an OmegaConf config to a primitive container.

Parameters:

cfg (Any) – the config to convert
resolve (bool) – True to resolve all values
throw_on_missing (bool) – When True, raise MissingMandatoryValue if any missing values are present. When False (the default), replace missing values with the string "???" in the output container.
enum_to_str (bool) – True to convert Enum keys and values to strings
structured_config_mode (SCMode) – Specify how Structured Configs (DictConfigs backed by a dataclass) are handled.
- By default (structured_config_mode=SCMode.DICT) structured configs are converted to plain dicts.
- If structured_config_mode=SCMode.DICT_CONFIG, structured config nodes will remain as DictConfig.
- If structured_config_mode=SCMode.INSTANTIATE, this function will instantiate structured configs (DictConfigs backed by a dataclass), by creating an instance of the underlying dataclass.

`to_object`

to_object(
    cfg: Any,
) -> dict[DictKeyType, Any] | list[Any] | tuple[Any, ...] | None | str | Any

Recursively converts an OmegaConf config to a primitive container. Any DictConfig objects backed by dataclasses or attrs classes are instantiated as instances of those backing classes.

This is an alias for OmegaConf.to_container(..., resolve=True, throw_on_missing=True, structured_config_mode=SCMode.INSTANTIATE)

Parameters:

cfg (Any) – the config to convert

Returns:

dict[DictKeyType, Any] | list[Any] | tuple[Any, ...] | None | str | Any – A dict, list, tuple, or dataclass representing this config.

`to_yaml`

to_yaml(
    cfg: Any,
    *,
    resolve: bool = False,
    sort_keys: bool = False,
    default_flow_style: bool | None = False
) -> str

returns a yaml dump of this config object.

Parameters:

cfg (Any) – Config object, Structured Config type or instance
resolve (bool) – if True, will return a string with the interpolations resolved, otherwise interpolations are preserved
sort_keys (bool) – If True, will print dict keys in sorted order. default False.
default_flow_style (bool | None) – PyYAML default_flow_style setting. default False.

Returns:

str – A string containing the yaml representation.

`typed_dict`

typed_dict(
    content: dict[Any, Any] | None = None,
    key_type: Any = Any,
    element_type: Any = Any,
) -> DictConfig

Create a DictConfig with explicit key and value types.

Useful for disambiguating assignment to a dict[str, X] | dict[str, Y] field when the value is empty or otherwise matches multiple candidates.

`typed_list`

typed_list(
    content: list[Any] | None = None, element_type: Any = Any
) -> ListConfig

Create a ListConfig with an explicit element type.

Useful for disambiguating assignment to a list[X] | list[Y] field when the value is empty or otherwise matches multiple candidates.

`typed_tuple`

typed_tuple(content: Any, tuple_type: Any = Tuple[Any, ...]) -> TupleConfig

Create and immediately validate a TupleConfig.

content is required because TupleConfig is structurally immutable. tuple_type accepts complete fixed or variadic tuple annotations, such as tuple[int, str] or tuple[int, ...].

`unsafe_merge`

unsafe_merge(
    *configs: DictConfig
    | ListConfig
    | TupleConfig
    | dict[DictKeyType, Any]
    | list[Any]
    | tuple[Any, ...]
    | Any
) -> ListConfig | TupleConfig | DictConfig

Merge a list of previously created configs into a single one This is much faster than OmegaConf.merge() as the input configs are not copied. However, the input configs must not be used after this operation as will become inconsistent.

Parameters:

configs (DictConfig | ListConfig | TupleConfig | dict[DictKeyType, Any] | list[Any] | tuple[Any, ...] | Any) – Input configs

Returns:

ListConfig | TupleConfig | DictConfig – the merged config object.

`update`

update(
    cfg: Container,
    key: str,
    value: Any = None,
    *,
    merge: bool = True,
    force_add: bool = False
) -> None

Update a value in a config using a key path.

The key path uses dot notation ("a.b.c") or bracket notation ("a[b][c]"), or a mix of both.

Keys containing special characters (., [, ], =) can be expressed by escaping them with a backslash:

r"a\.b" — targets the key "a.b" (single key with a literal dot)
r"a\[0\]" — targets the key "a[0]"
r"a\=b" — targets the key "a=b"

Parameters:

cfg (Container) – input config to update
key (str) – key path to update (dot/bracket notation, backslash-escapable)
value (Any) – value to set, if value if a list or a dict it will be merged or set depending on merge_config_values
merge (bool) – If value is a dict or a list, True (default) to merge into the destination, False to replace the destination.
force_add (bool) – insert the entire path regardless of Struct flag or Structured Config nodes.

`Resolver`

Resolver = Callable[..., Any]

`SI`

SI(interpolation: str) -> Any

Use this for String interpolation, for example "http://${host}:${port}"

Parameters:

interpolation (str) – interpolation string

Returns:

Any – input interpolation with type Any

`flag_override`

flag_override(
    config: Node,
    names: list[str] | str,
    values: list[bool | None] | bool | None,
) -> Generator[Node, None, None]

Context manager that temporarily overrides one or more flags on config.

The original flag values are restored on exit, even if an exception is raised.

Parameters:

config (Node) – An OmegaConf node whose flags will be overridden.
names (list[str] | str) – Flag name or list of flag names (e.g. "readonly", "struct").
values (list[bool | None] | bool | None) – New value or list of values corresponding to names.

Returns:

Generator[Node, None, None] – Yields config with the overridden flags.

`open_dict`

open_dict(config: Container) -> Generator[Container, None, None]

Context manager that temporarily disables struct mode on config.

While active, new keys can be added freely. The original struct state is restored on exit, even if an exception is raised.

Parameters:

config (Container) – An OmegaConf container.

Returns:

Generator[Container, None, None] – Yields config with struct mode disabled.

`read_write`

read_write(config: Node) -> Generator[Node, None, None]

Context manager that temporarily makes config writable.

The original read-only state is restored on exit, even if an exception is raised.

Parameters:

config (Node) – An OmegaConf node.

Returns:

Generator[Node, None, None] – Yields config in a writable state.

II​

MISSING​

OmegaConf​

can_select​

clear_cache​

clear_resolver​

clear_resolvers​

copy_cache​

create​

from_cli​

from_dotlist​

get_cache​

get_type​

has_resolver​

is_config​

is_dict​

is_interpolation​

is_list​

is_missing​

is_readonly​

is_sequence​

is_struct​

is_tuple​

legacy_register_resolver​

load​

masked_copy​

merge​

missing_keys​

register_new_resolver​

register_resolver​

resolve​

save​

select​

set_cache​

set_readonly​

set_struct​

structural_equality​

structured​

to_container​

to_object​

to_yaml​

typed_dict​

typed_list​

typed_tuple​

unsafe_merge​

update​

Resolver​

SI​

flag_override​

open_dict​

read_write​

`II`

`MISSING`

`OmegaConf`

`can_select`

`clear_cache`

`clear_resolver`

`clear_resolvers`

`copy_cache`

`create`

`from_cli`

`from_dotlist`

`get_cache`

`get_type`

`has_resolver`

`is_config`

`is_dict`

`is_interpolation`

`is_list`

`is_missing`

`is_readonly`

`is_sequence`

`is_struct`

`is_tuple`

`legacy_register_resolver`

`load`

`masked_copy`

`merge`

`missing_keys`

`register_new_resolver`

`register_resolver`

`resolve`

`save`

`select`

`set_cache`

`set_readonly`

`set_struct`

`structural_equality`

`structured`

`to_container`

`to_object`

`to_yaml`

`typed_dict`

`typed_list`

`typed_tuple`

`unsafe_merge`

`update`

`Resolver`

`SI`

`flag_override`

`open_dict`

`read_write`