OmegaConf 2.4.0rc1

2.4.0rc1 (2026-09-28)

Introduction

OmegaConf 2.4.0rc1 previews the first feature release since 2.3.0 in 2022. It
fixes all open bug reports, delivers a broad set of new features, and refreshes
the roadmap for work beyond this release. Highlights include richer structured
config typing with Literal, container unions, and experimental tuples,
alongside improvements to interpolation, resolvers, merging, and validation.

This release includes compatibility changes. Python 3.10 or newer is required;
native tuples now become immutable TupleConfig values; and some implicit
conversions during assignment now warn. Review the API changes below and report
regressions before the final release.

Features

• Add support for the | and |= operators on DictConfig. cfg1 | cfg2 returns a new merged config (equivalent to OmegaConf.merge(cfg1, cfg2)), and cfg1 |= cfg2 merges in place (equivalent to cfg1.merge_with(cfg2)). These operators are not supported on ListConfig and will raise a TypeError. (#1006)
• OmegaConf.to_yaml() now accepts default_flow_style to control YAML collection flow style. (#1075)
• Added OmegaConf.can_select() for checking if a select-style key path can produce a value without returning a default or raising. (#1129)
• The YAML parser will now use yaml.CSafeLoader instead of yaml.SafeLoader whenever possible to speed up parsing (#1150)
• The YAML dumper will now use yaml.CDumper instead of yaml.Dumper whenever possible to speed up dumping (#1152)
• Added support for assigning string-valued enums in structured configs from either the enum member name or the enum value. (#1182)
• When accessing a missing key, OmegaConf now suggests similar key names if any exist (e.g. "Did you mean: 'missing'?"). (#1221)
• Support typing.Literal annotations in structured configs, including as members of unions. (#1228, #1271)
• Key paths in OmegaConf.update(), OmegaConf.select(), OmegaConf.from_dotlist(), and OmegaConf.from_cli() now support backslash escaping so that keys whose names contain literal dots, brackets, or equals signs can be addressed (e.g. r"a\.b" selects the key "a.b"). (#1230)
• Structured configs now support unions of typed containers (e.g. Union[List[int], Dict[str, int]]). OmegaConf.typed_list([], element_type=str) creates an empty list typed as List[str], selecting that branch of Union[List[int], List[str]]; OmegaConf.typed_dict() similarly specifies dictionary key and value types. (#1261)
• Support structured config types as members of unions, with type-driven branch selection and explicit handling for ambiguous mappings. (#1275)
• Added OmegaConf.structural_equality() for comparing configs by unresolved container structure. (#1326)
• Add the oc.coerce resolver to explicitly convert values using OmegaConf primitive node types before destination validation. (#1332)
• Node interpolations can address keys containing literal dots, brackets, colons, or backslashes. (#1335)
• Support Any in Union annotations and transparent PEP 695 type aliases. (#144)
• Custom resolvers can now validate runtime arguments and return values against their annotations using explicit "off", "warn", and "error" policies. OmegaConf 2.4 defaults to advisory warnings. (#612)

Bug Fixes

• Fix merging an interpolation into a structured config field failing with InterpolationKeyError or ValidationError; the interpolation is now kept unresolved and resolved lazily against the merged result. (#1020)
• Preserve structured list element types when merging a plain list into a missing structured config list field. (#1058)
• Fixed a crash in OmegaConf.unsafe_merge when merging structured configs containing union types. (#1087)
• Fix merging enum names into nested lists in structured configs. (#1095)
• Fixed OmegaConf.merge() and OmegaConf.unsafe_merge() with nested readonly structured configs. (#1102)
• Fix OmegaConf.missing_keys() raising when an interpolation dereferences a missing value, and add a resolve_custom_resolvers flag to opt into custom resolver evaluation. (#1118)
• Improved missing-key errors for relative interpolations by showing both the original interpolation key and the resolved lookup path. (#1126)
• Fixed OmegaConf.select and oc.select to return the provided default when a relative key climbs above the config root. (#1127)
• OmegaConf.create() now supports collections.OrderedDict as both a top-level input and a nested value. (#1156)
• Fixed OmegaConf.resolve() raising UnsupportedValueType when a custom resolver returns a dict or list. (#1165)
• Fixed validation for union-typed values nested in structured config containers during merges and interpolation resolution. (#1166)
• Fixed structured config support for forward references inside container
  annotations on Python 3.10 and older. (#1174)
• Preserve container identity when assigning a config node to itself. (#1177)
• Fix duplicate key handling during YAML anchor merge operations (#1194)
• Changed OmegaConf.create(None) to return literal None instead of a DictConfig(None) wrapper. This is a breaking change for code that relied on getting a config object back from create(None). (#1196)
• Fixed a bug where merging a missing structured config into an unresolved interpolation could replace the interpolation with the structured type's default value instead of preserving the interpolation. (#1205)
• Fix OmegaConf.resolve() raising RuntimeError on Python 3.12+ when a custom resolver returns a DictConfig. (#1239)
• OmegaConf.update() now raises a ConfigTypeError with a clear message when navigating through a structured Optional node that is None, instead of an AssertionError. (#1280)
• Fix OmegaConf exceptions retaining caller frame locals through traceback reference cycles. (#1295, #1314)
• Fix ListConfig iteration leaking UnionNode wrappers for List[Union[...]]; iteration now yields the selected concrete values, matching indexing. (#1310)
• OmegaConf.update() now follows intermediate node interpolations whose
  reference chains end at existing config containers, applying nested updates to
  the referenced container while preserving the interpolation. (#1329)
• Keep the failing key and object type on interpolation errors raised through OmegaConf.resolve(), so they match the errors raised by direct node access. (#1330)
• OmegaConf.resolve() now resolves nested interpolations in resolver-returned containers in one call, including when another field refers to the container before its field is visited. (#1334)
• Inherited flags are now updated correctly for containers selected by a union type. (#1340)
• Select matching Literal members before broader scalar members in unions, regardless of annotation order. (#1357)
• OmegaConf.merge() and OmegaConf.unsafe_merge() no longer fail with an AttributeError when merging into a null dictionary root, including optional Structured Config fields. (#1360)
• Removed the internal flags argument from _ensure_container and made merge conversion preserve allow_objects explicitly. (#580)
• Integer interpolation segm...

OmegaConf 2.3.1

2.3.1 (2026-06-11)

Bug Fixes

• Fix source installs with setuptools versions that no longer provide pkg_resources. (#1315)

OmegaConf 2.3.0

2.3.0 (2022-12-06)

Features:

• Support python3.11 (#1023)
• Support interpolation to keys that contain a non-leading dash character (#880)
• OmegaConf now inspects the metadata of structured config fields and ignores fields where metadata["omegaconf_ignore"] is True. (#984)

Bug Fixes:

• Fix an issue where merging of nested structured configs could incorrectly result in an exception (#1003)

Links:

• OmegaConf on pypi
• OmegaConf 2.3 docs

OmegaConf 2.2.3

2.2.3 (2022-08-18)

Bug Fixes

• Revert an accidental behavior change where implicit conversion from Path to str was disallowed. (#934)
• ListConfig sliced assignment now avoids partial updates upon error (#950)
• Fix a bug that caused OmegaConf to crash when processing attr classes whose field annotations contained forward-references. (#963)
• Improve error message when certain illegal type annotations (such as typing.Sequence) are used in structured configs. (#991)
• When parsing yaml: Disallow numbers with trailing underscore from being converted to float. (#838)

API changes and deprecations

• In structured config type hints, OmegaConf now treats tuple as equivalent to typing.Tuple, and likewise for dict/Dict and list/List. (#973)

OmegaConf 2.2.2

2.2.2 (2022-05-26)

Bug Fixes

• Revert an accidental behavior change where implicit conversion from Path to str was disallowed. (#934)
• Revert a behavior change where namedtuples and list subclasses were coerced to ListConfig. (#939)
• Fix a bug where the oc.dict.values resolver failed when passed a relative dotpath (#942)

OmegaConf 2.2.1

2.2.1 (2022-05-17)

OmegaConf 2.2 is a major release. The most significant area of improvement in
2.2 is support for more flexible type hints in structured configs. In addition,
OmegaConf now natively supports two new primitive types, bytes and pathlib.Path.

Features

• Support unions of primitive types in structured config type hints (typing.Union) (#144)
• Support nested container type hints in structured configs, e.g. dict-of-dict and list-of-list (#427)
• Improve support for optional element types in structured config container type hints (typing.Optional) (#460)
• Add support for bytes-typed values (#844)
• Add support for pathlib.Path-typed values (#97)
• ListConfig now implements slice assignment (#736)
• Enable adding a ListConfig to a list via the ListConfig.__radd__ dunder method (#849)
• Add OmegaConf.missing_keys(), a method that returns the missing keys in a config object (#720)
• Add OmegaConf.clear_resolver(), a method to remove interpolation resolvers by name (#769)
• Enable the use of a pipe symbol | in unquoted strings in OmegaConf interpolations (#799)

Bug Fixes

• OmegaConf.to_object now works properly with structured configs that have init=False fields (#789)
• Fix bugs related to creation of structured configs from dataclasses having fields with a default_factory (#831)
• Fix default value initialization for structured configs created from subclasses of dataclasses (#817)

API changes and deprecations

• Removed support for OmegaConf.is_none(cfg, "key"). Please use cfg.key is None instead. (#547)
• Removed support for ${env} interpolations. ${oc.env} should be used instead. (#573)
• Removed OmegaConf.get_resolver(). Please use OmegaConf.has_resolver() instead. (#608)
• Removed support for OmegaConf.is_optional(). (#698)
• Improved error message when assigning an invalid value to int or float config nodes (#743)
• To conform with the MutableMapping API, the DictConfig.items method now returns an object of type ItemsView, and DictConfig.keys will now always return a KeysView (#848)

OmegaConf 2.1.1

2.1.1 (2021-08-19)

Features

• Add a throw_on_missing keyword argument to the signature of OmegaConf.to_container, which controls whether MissingMandatoryValue exceptions are raised. (#501)

Miscellaneous changes

• Update pyyaml dependency specification for compatibility with PEP440 (#758)
• Fix a packaging issue (missing sdist dependency) (#772

OmegaConf 2.1.0

2.1.0 (2021-06-07)

OmegaConf 2.1 is a major release introducing substantial new features, and introducing some incompatible changes.
The biggest area of improvement in 2.1 is interpolations and resolvers. In addition - OmegaConf containers are now
much more compatible with their plain Python container counterparts (dict and list).

Features

API Enhancements

• OmegaConf.select() now takes an optional default value to return if a key is not found (#228)
• flag_override can now override multiple flags at the same time (#400)
• Add the OmegaConf.to_object method, which converts Structured Configs to native instances of the underlying @dataclass or @attr.s class. (#472)
• Add OmegaConf.unsafe_merge(), a fast merge variant that destroys the input configs (#482)
• New function OmegaConf.has_resolver() allows checking whether a resolver has already been registered. (#608)
• Adds OmegaConf.resolve(cfg) for in-place interpolation resolution on cfg (#640)
• force_add flag added to OmegaConf.update(), ensuring that the path is created even if it will result in insertion of new values into struct nodes. (#664)
• Add DictConfig support for keys of type int, float and bool (#149), (#483)
• Structured Configs fields without a value are now automatically treated as OmegaConf.MISSING (#390)
• Add minimal support for typing.TypedDict (#473)
• OmegaConf.to_container now takes a structured_config_mode keyword argument. Setting structured_config_mode=SCMode.DICT_CONFIG causes to_container to not convert Structured Config objects to python dicts (it leaves them as DictConfig objects). (#548)

Interpolation and resolvers

• Support for relative interpolation (#48)
• Add ability to nest interpolations, e.g. ${foo.${bar}}}, ${oc.env:{$var1},${var2}}, or ${${func}:x1,x2} (#445)
• Custom resolvers can now access the parent and the root config nodes (#266)
• For OmegaConf.{update, select} and in interpolations, bracketed keys may be used as an alternative form to dot notation,
  e.g. foo.1 is equivalent to foo[1], [foo].1 and [foo][1]. (#179)
• Custom resolvers may take non string arguments as input, and control whether to use the cache. (#445)
• Dots may now be used in resolver names to denote namespaces (e.g: ${namespace.my_func:123}) (#539)
• New resolver oc.select, enabling node selection with a default value to use if the node cannot be selected (#541)
• New resolver oc.decode that can be used to automatically convert a string to bool, int, float, dict, list, etc. (#574)
• New resolvers oc.dict.keys and oc.dict.values provide a list view of the keys or values of a DictConfig node. (#643)
• New resolver oc.create can be used to dynamically generate config nodes (#645)
• New resolver oc.deprecated, that enables deprecating config nodes (#681)
• The dollar character $ is now allowed in interpolated key names, e.g. ${$var} (#600)

Misc

• New PyDev.Debugger resolver plugin for easier debugging in PyCharm and VSCode (#214)
• OmegaConf now supports Python 3.9 (#447)
• Support for Python 3.10 postponed annotation evaluation (#303)
• Experimental support for enabling objects in config via "allow_objects" flag (#382)

Bug Fixes

• ListConfig.append() now copies input config nodes (#601)
• Fix loading of OmegaConf 2.0 pickled configs (#718)
• Fix support for forward declarations in Dict and Lists (#378)
• Fix bug that allowed instances of Structured Configs to be assigned to DictConfig with different element type. (#386)
• Fix exception raised when checking for the existence of a key with an incompatible type in DictConfig (#394)
• Fix loading of an empty file via a file-pointer to return an empty dictionary (#403)
• Fix pickling of Structured Configs with fields annotated as Dict[KT, VT] or List[T] on Python 3.6. (#407)
• Assigning a primitive type to a Subscripted Dict now raises a descriptive message. (#409)
• Fix assignment of an invalid value to a DictConfig to raise an exception without modifying the config object (#409)
• Assigning a Structured Config to a Dict annotation now raises a descriptive error message. (#410)
• OmegaConf.to_container() raises a ValueError on invalid input (#418)
• Fix ConfigKeyError in some cases when merging lists containing interpolation values (#422)
• DictConfig.get() in struct mode return None like standard Dict for non-existing keys (#425)
• Fix bug where interpolations were unnecessarily resolved during merge (#431)
• Fix bug where assignment of an invalid value to a ListConfig raised an exception but left the object modified. (#433)
• When initializing a Structured Config with an incorrectly-typed value, the resulting ValidationError now properly reports the offending value in its error message. (#435)
• Fix assignment of a Container to itself causing it to clear its content (#449)
• Fix bug where DictConfig's shallow copy didn't work properly in some cases. (#450)
• Fix support for merge tags in YAML files (#470)
• Fix merge into a custom resolver node that raises an exception (#486)
• Fix merge when element type is a Structured Config (#496)
• Fix ValidationError when setting to None an optional field currently interpolated to a non-optional one (#524)
• Fix OmegaConf.to_yaml(cfg) when keys are of Enum type (#531)
• When a DictConfig has enum-typed keys, __delitem__ can now be called with a string naming the enum member to be deleted. (#554)
• OmegaConf.select() of a missing (???) node from a ListConfig with throw_on_missing set to True now raises the intended exception. (#563)
• DictConfig.{get(),pop()} now return None when the accessed key evaluates to None, instead of the specified default value (for consistency with regular Python dictionaries). (#583)
• ListConfig.get() now return None when the accessed key evaluates to None, instead of the specified default value (for consistency with DictConfig). (#583)
• Fix creation of structured config from a dict subclass: data from the dict is no longer thrown away. (#584)
• Assignment of a dict/list to an existing node in a parent in struct mode no longer raises ValidationError (#586)
• Nested flag_override now properly restore the original state (#589)
• Fix OmegaConf.create() to set the provided parent when creating a config from a YAML string. (#648)
• OmegaConf.select now returns None when attempting to select a child of a value or None node (#678)
• Improve error message when creating a config from a Structured Config that fails type validation (#697)

API changes and deprecations

• DictConfig __getattr__ access, e.g. cfg.foo, is now raising a AttributeError if the key "foo" does not exist (#515)
• DictConfig __getitem__ access, e.g. cfg["foo"], is now raising a KeyError if the key "foo" does not exist (#515)
• DictConfig get access, e.g. cfg.get("foo"), now returns None if the key "foo" does not exist ([#527...

OmegaConf 2.1.0.rc1

2.1.0.rc1 (2021-05-12)

OmegaConf 2.1 is a major release introducing substantial new features, and introducing some incompatible changes.
The biggest area of improvement in 2.1 is interpolations and resolvers. In addition - OmegaConf containers are now
much more compatible with their plain Python container counterparts (dict and list).

Features

API Enhancements

• OmegaConf.select() now takes an optional default value to return if a key is not found (#228)
• flag_override can now override multiple flags at the same time (#400)
• Add the OmegaConf.to_object method, which converts Structured Configs to native instances of the underlying @dataclass or @attr.s class. (#472)
• Add OmegaConf.unsafe_merge(), a fast merge variant that destroys the input configs (#482)
• New function OmegaConf.has_resolver() allows checking whether a resolver has already been registered. (#608)
• Adds OmegaConf.resolve(cfg) for in-place interpolation resolution on cfg (#640)
• force_add flag added to OmegaConf.update(), ensuring that the path is created even if it will result in insertion of new values into struct nodes. (#664)
• Add DictConfig support for keys of type int, float and bool (#149), (#483)
• Structured Configs fields without a value are now automatically treated as OmegaConf.MISSING (#390)
• Add minimal support for typing.TypedDict (#473)
• OmegaConf.to_container now takes a structured_config_mode keyword argument. Setting structured_config_mode=SCMode.DICT_CONFIG causes to_container to not convert Structured Config objects to python dicts (it leaves them as DictConfig objects). (#548)

Interpolation and resolvers

• Support for relative interpolation (#48)
• Add ability to nest interpolations, e.g. ${foo.${bar}}}, ${oc.env:{$var1},${var2}}, or ${${func}:x1,x2} (#445)
• Custom resolvers can now access the parent and the root config nodes (#266)
• For OmegaConf.{update, select} and in interpolations, bracketed keys may be used as an alternative form to dot notation,
  e.g. foo.1 is equivalent to foo[1], [foo].1 and [foo][1]. (#179)
• Custom resolvers may take non string arguments as input, and control whether to use the cache. (#445)
• Dots may now be used in resolver names to denote namespaces (e.g: ${namespace.my_func:123}) (#539)
• New resolver oc.select, enabling node selection with a default value to use if the node cannot be selected (#541)
• New resolver oc.decode that can be used to automatically convert a string to bool, int, float, dict, list, etc. (#574)
• New resolvers oc.dict.keys and oc.dict.values provide a list view of the keys or values of a DictConfig node. (#643)
• New resolver oc.create can be used to dynamically generate config nodes (#645)
• New resolver oc.deprecated, that enables deprecating config nodes (#681)
• The dollar character $ is now allowed in interpolated key names, e.g. ${$var} (#600)

Misc

• New PyDev.Debugger resolver plugin for easier debugging in PyCharm and VSCode (#214)
• OmegaConf now supports Python 3.9 (#447)
• Support for Python 3.10 postponed annotation evaluation (#303)
• Experimental support for enabling objects in config via "allow_objects" flag (#382)

Bug Fixes

• Fix support for forward declarations in Dict and Lists (#378)
• Fix bug that allowed instances of Structured Configs to be assigned to DictConfig with different element type. (#386)
• Fix exception raised when checking for the existence of a key with an incompatible type in DictConfig (#394)
• Fix loading of an empty file via a file-pointer to return an empty dictionary (#403)
• Fix pickling of Structured Configs with fields annotated as Dict[KT, VT] or List[T] on Python 3.6. (#407)
• Assigning a primitive type to a Subscripted Dict now raises a descriptive message. (#409)
• Fix assignment of an invalid value to a DictConfig to raise an exception without modifying the config object (#409)
• Assigning a Structured Config to a Dict annotation now raises a descriptive error message. (#410)
• OmegaConf.to_container() raises a ValueError on invalid input (#418)
• Fix ConfigKeyError in some cases when merging lists containing interpolation values (#422)
• DictConfig.get() in struct mode return None like standard Dict for non-existing keys (#425)
• Fix bug where interpolations were unnecessarily resolved during merge (#431)
• Fix bug where assignment of an invalid value to a ListConfig raised an exception but left the object modified. (#433)
• When initializing a Structured Config with an incorrectly-typed value, the resulting ValidationError now properly reports the offending value in its error message. (#435)
• Fix assignment of a Container to itself causing it to clear its content (#449)
• Fix bug where DictConfig's shallow copy didn't work properly in some cases. (#450)
• Fix support for merge tags in YAML files (#470)
• Fix merge into a custom resolver node that raises an exception (#486)
• Fix merge when element type is a Structured Config (#496)
• Fix ValidationError when setting to None an optional field currently interpolated to a non-optional one (#524)
• Fix OmegaConf.to_yaml(cfg) when keys are of Enum type (#531)
• When a DictConfig has enum-typed keys, __delitem__ can now be called with a string naming the enum member to be deleted. (#554)
• OmegaConf.select() of a missing (???) node from a ListConfig with throw_on_missing set to True now raises the intended exception. (#563)
• DictConfig.{get(),pop()} now return None when the accessed key evaluates to None, instead of the specified default value (for consistency with regular Python dictionaries). (#583)
• ListConfig.get() now return None when the accessed key evaluates to None, instead of the specified default value (for consistency with DictConfig). (#583)
• Fix creation of structured config from a dict subclass: data from the dict is no longer thrown away. (#584)
• Assignment of a dict/list to an existing node in a parent in struct mode no longer raises ValidationError (#586)
• Nested flag_override now properly restore the original state (#589)
• Fix OmegaConf.create() to set the provided parent when creating a config from a YAML string. (#648)
• OmegaConf.select now returns None when attempting to select a child of a value or None node (#678)
• Improve error message when creating a config from a Structured Config that fails type validation (#697)

API changes and deprecations

• DictConfig __getattr__ access, e.g. cfg.foo, is now raising a AttributeError if the key "foo" does not exist (#515)
• DictConfig __getitem__ access, e.g. cfg["foo"], is now raising a KeyError if the key "foo" does not exist (#515)
• DictConfig get access, e.g. cfg.get("foo"), now returns None if the key "foo" does not exist (#527)
• Omegaconf.select(cfg, key, default, throw_on_missing) now requires keyword arguments for everything after key ([#228](https://github.com/omry/omegaconf/iss...

OmegaConf 2.0.6

2.0.6 (2021-01-19)

Bug Fixes

• Fix bug where DictConfig's shallow copy didn't work properly in some cases. (#450)