NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #633 most downloaded on PyPI
A flexible configuration library
Last release 6 days ago
28 Sep 2026
Ships unpredictably
gaps range from 9 days to 1.7 years
Some releases are documented
notes for 16 of 45 stable releases
19 versions withdrawn
withdrawn after publishing
8 years old
157 releases · first in 2018
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…
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.
| 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.can_select() for checking if a select-style key path can produce a value without returning a default or raising. (#1129)yaml.CSafeLoader instead of yaml.SafeLoader whenever possible to speed up parsing (#1150)yaml.CDumper instead of yaml.Dumper whenever possible to speed up dumping (#1152)typing.Literal annotations in structured configs, including as members of unions. (#1228, #1271)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)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)oc.coerce resolver to explicitly convert values using OmegaConf primitive node types before destination validation. (#1332)Any in Union annotations and transparent PEP 695 type aliases. (#144)"off", "warn", and "error" policies. OmegaConf 2.4 defaults to advisory warnings. (#612)OmegaConf.unsafe_merge when merging structured configs containing union types. (#1087)OmegaConf.merge() and OmegaConf.unsafe_merge() with nested readonly structured configs. (#1102)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)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)OmegaConf.resolve() raising UnsupportedValueType when a custom resolver returns a dict or list. (#1165)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)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)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 whoseOmegaConf.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)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)flags argument from _ensure_container and made merge conversion preserve allow_objects explicitly. (#580)OmegaConf.select() and OmegaConf.update() can now resolve integer dictionary keys. Configurations reject ambiguous pairs such as 1 and "1". (#651)typing.Generic. (#731)ListConfig.insert() now follows Python list semantics for negative and out-of-range indices and leaves the list unchanged when validation fails. (#750)ListConfig negative index behavior more closely with Python lists by supporting negative list-index interpolations and by fixing negative slicing edge cases such as cfg.xs[:-1] on empty lists. (#755)OmegaConf.masked_copy losing typed leaf node classes at the top level of the copy. (#813)attrs classes that use a default factory (attrs.Factory). (#945)OmegaConf.resolve() now raises InterpolationToMissingValueError when an interpolation dereferences to a missing (???) value, instead of silently overwriting the node with ???. This restores the invariant that working with a resolved config gives the same results as working with the unresolved config. (#1131)\. \[ \] \=) now escapes that character rather than being treated as a literal backslash followed by an active delimiter. This affects only the rare case of keys whose names end with a backslash: OmegaConf.select(cfg, r"a\.b") previously navigated to key "a\" then "b"; it now resolves to the single key "a.b". Keys ending in a backslash are not idiomatic in YAML and this change is unlikely to be encountered in practice. (#1230)OmegaConf.to_container(..., resolve=True) now resolves each custom resolver at most once within a single conversion pass, even when multiple interpolations reference the same resolved node. This brings its behavior in line with OmegaConf.resolve() for such cases. (#1243)??? values with \??? across interpolation, resolvers, and YAML. Plain ??? returned by a resolver is now missing on access. (#1302)DictConfig and ListConfig unhashable, preventing their use as dictionary keys or set elements. (#1333)TupleConfig instead of being converted to a mutable ListConfig. Code that expects tuple input to support list mutation, checks only OmegaConf.is_list(), or expects OmegaConf.to_container() to return a list for tuple input must be updated. Use OmegaConf.is_tuple() for tuple-specific behavior, OmegaConf.is_sequence() when either sequence type is accepted, or pass a list explicitly when mutation is required. Tuple annotations support fixed positional and homogeneous variadic types, complete replacement merges, typed container unions, native tuple conversion, and tuple-style sequence operations. Tuple semantics are experimental in OmegaConf 2.4 and feedback is welcome. (#392)OmegaConf.update() for explicit conversion. Assigning structured-config objects or classes to structured-config fields retains its existing behavior. (#459)OmegaConf.get_type() to return NoneType for OmegaConf nodes containing None, and validate None/NoneType annotations. (#928)OmegaConf.register_resolver() as the canonical custom resolver API, and deprecated OmegaConf.register_new_resolver() and OmegaConf.legacy_register_resolver(). (#969)create, structured, load, from_cli, has_resolver, get_cache, set_cache, clear_cache, copy_cache, set_readonly, is_readonly, set_struct, is_struct, is_missing, is_interpolation, is_list, is_dict, is_config, get_type, flag_override, read_write, and open_dict. (#1222)OmegaConf.merge behavior with MISSING values: a missing value on the source side does not overwrite a non-missing value on the target. (#771)antlr4 runtime is now vendored to prevent conflicts with other dependencies. (#1091)One column per quarter.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Merge branch '2.4_branch' of github.com:omry/omegaconf into 2.4_branch
Merge branch '2.4_branch' of github.com:omry/omegaconf into 2.4_branch
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix source installs with setuptools versions that no longer provide pkg_resources.
Support interpolation to keys that contain a non-leading dash character
metadata["omegaconf_ignore"] is True. (#984)Nothing published for this version
Nothing published for this version
Nothing published for this version
Revert an accidental behavior change where implicit conversion from Path to str was disallowed.
Path to str was disallowed. (#934)typing.Sequence) are used in structured configs. (#991)tuple as equivalent to typing.Tuple, and likewise for dict/Dict and list/List. (#973)Revert an accidental behavior change where implicit conversion from Path to str was disallowed.
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 ad
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.
typing.Union) (#144)typing.Optional) (#460)bytes-typed values (#844)pathlib.Path-typed values (#97)ListConfig now implements slice assignment (#736)ListConfig to a list via the ListConfig.__radd__ dunder method (#849)OmegaConf.missing_keys(), a method that returns the missing keys in a config object (#720)OmegaConf.clear_resolver(), a method to remove interpolation resolvers by name (#769)| in unquoted strings in OmegaConf interpolations (#799)OmegaConf.to_object now works properly with structured configs that have init=False fields (#789)OmegaConf.is_none(cfg, "key"). Please use cfg.key is None instead. (#547)${env} interpolations. ${oc.env} should be used instead. (#573)OmegaConf.get_resolver(). Please use OmegaConf.has_resolver() instead. (#608)OmegaConf.is_optional(). (#698)MutableMapping API, the DictConfig.items method now returns an object of type ItemsView, and DictConfig.keys will now always return a KeysView (#848)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Add a throw_on_missing keyword argument to the signature of OmegaConf.to_container, which controls whether MissingMandatoryValue exceptions are raised
New resolver oc.deprecated , that enables deprecating config nodes
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).
@dataclass or @attr.s class. (#472)OmegaConf.has_resolver() allows checking whether a resolver has already been registered. (#608)OmegaConf.MISSING (#390)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)OmegaConf.{update, select} and in interpolations, bracketed keys may be used as an alternative form to dot notation,${namespace.my_func:123}) (#539)oc.select, enabling node selection with a default value to use if the node cannot be selected (#541)oc.decode that can be used to automatically convert a string to bool, int, float, dict, list, etc. (#574)oc.dict.keys and oc.dict.values provide a list view of the keys or values of a DictConfig node. (#643)oc.create can be used to dynamically generate config nodes (#645)oc.deprecated, that enables deprecating config nodes (#681)$ is now allowed in interpolated key names, e.g. ${$var} (#600)ListConfig.append() now copies input config nodes (#601)__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)parent when creating a config from a YAML string. (#648)__getattr__ access, e.g. cfg.foo, is now raising a AttributeError if the key "foo" does not exist (#515)__getitem__ access, e.g. cfg["foo"], is now raising a KeyError if the key "foo" does not exist (#515)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)???) instead of auto-expanding (#411)register_resolver() is deprecated in favor of register_new_resolver(), allowing resolvers to (i) take non-string arguments like int, float, dict, interpolations, etc. and (ii) control the cache behavior (now disabled by default) (#426)OmegaConf.select(), DictConfig.{get(),pop()}, ListConfig.{get(),pop()} no longer return the specified default value when the accessed key is an interpolation that cannot be resolved: instead, an exception is raised. (#543)InterpolationResolutionError or a subclass of it. (#561)key in cfg now returns True when key is an interpolation even if the interpolation target is a missing ("???") value. (#562)OmegaConf.select() as well as container methods get() and pop() do not return their default value anymore when the accessed key is an interpolation that cannot be resolved: instead, an exception is raised. (#565)${foo:a,}) are deprecated in favor of explicit quoted strings (e.g., ${foo:a,""}) (#572)env resolver is deprecated in favor of oc.env, which keeps the string representation of environment variables, does not cache the resulting value, and handles "null" as default value. (#573)OmegaConf.get_resolver() is deprecated: use the new OmegaConf.has_resolver() to check for the existence of a resolver. (#608)typing.Dict is now deprecated. (#663)New resolver oc.deprecated , that enables deprecating config nodes
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).
@dataclass or @attr.s class. (#472)OmegaConf.has_resolver() allows checking whether a resolver has already been registered. (#608)OmegaConf.MISSING (#390)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)OmegaConf.{update, select} and in interpolations, bracketed keys may be used as an alternative form to dot notation,${namespace.my_func:123}) (#539)oc.select, enabling node selection with a default value to use if the node cannot be selected (#541)oc.decode that can be used to automatically convert a string to bool, int, float, dict, list, etc. (#574)oc.dict.keys and oc.dict.values provide a list view of the keys or values of a DictConfig node. (#643)oc.create can be used to dynamically generate config nodes (#645)oc.deprecated, that enables deprecating config nodes (#681)$ is now allowed in interpolated key names, e.g. ${$var} (#600)__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)parent when creating a config from a YAML string. (#648)__getattr__ access, e.g. cfg.foo, is now raising a AttributeError if the key "foo" does not exist (#515)__getitem__ access, e.g. cfg["foo"], is now raising a KeyError if the key "foo" does not exist (#515)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)???) instead of auto-expanding (#411)register_resolver() is deprecated in favor of register_new_resolver(), allowing resolvers to (i) take non-string arguments like int, float, dict, interpolations, etc. and (ii) control the cache behavior (now disabled by default) (#426)OmegaConf.select(), DictConfig.{get(),pop()}, ListConfig.{get(),pop()} no longer return the specified default value when the accessed key is an interpolation that cannot be resolved: instead, an exception is raised. (#543)InterpolationResolutionError or a subclass of it. (#561)key in cfg now returns True when key is an interpolation even if the interpolation target is a missing ("???") value. (#562)OmegaConf.select() as well as container methods get() and pop() do not return their default value anymore when the accessed key is an interpolation that cannot be resolved: instead, an exception is raised. (#565)${foo:a,}) are deprecated in favor of explicit quoted strings (e.g., ${foo:a,""}) (#572)env resolver is deprecated in favor of oc.env, which keeps the string representation of environment variables, does not cache the resulting value, and handles "null" as default value. (#573)OmegaConf.get_resolver() is deprecated: use the new OmegaConf.has_resolver() to check for the existence of a resolver. (#608)typing.Dict is now deprecated. (#663)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix bug where DictConfig's shallow copy didn't work properly in some cases.
Fix bug where interpolations were unnecessarily resolved during merge
Your coding agent can read these notes before it upgrades. Set up the MCP server →