pypi / omegaconf
omegaconf
What changed in omegaconf 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-13.
23 breaking4 deprecations20 new APIs and options2 performance11 behavior and defaults18 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initomegaconf 278 changes
Breaking changes 23
DictConfig and ListConfig are unhashable and cannot be used as dictionary keys or set elements.
OmegaConf.create(None) returns literal None instead of a DictConfig(None) wrapper.
Returns NoneType for OmegaConf nodes containing None and validates None/NoneType annotations.
Use is_tuple for tuple-specific behavior; is_sequence accepts either sequence type.
Raises InterpolationToMissingValueError when an interpolation dereferences to a missing value instead of silently overwriting the node with ???.
Raises ConfigTypeError with a clear message when navigating through a structured Optional node that is None, rather than AssertionError.
Integer interpolation segments and integer-looking string paths can resolve integer dictionary keys; configurations reject ambiguous pairs such as 1 and "1".
Python 3.10 or newer is required; support for Python 3.6 through 3.9 has been dropped.
Native tuples now create a structurally immutable TupleConfig instead of a mutable ListConfig; tuple semantics are experimental.
Lazy access now validates and converts interpolated values against their destination type, matching eager resolution.
Alias expansion is limited by default to avoid excessive config growth from crafted YAML input, with an environment override for trusted configurations.
pretty() preserves insertion order by default instead of sorting keys; set sort_keys=True to override.
Deleting an item raises ConfigTypeError when the config is in struct mode.
pop now returns the underlying value rather than a ValueNode.
pop() raises ConfigTypeError when the config is in struct mode.
cfg.save() was removed; use OmegaConf.save().
cfg.to_container() was removed; use OmegaConf.to_container().
Merging into a node interpolation now copies the target node by value.
omegaconf.Config was renamed to omegaconf.Container.
select(key) returns the root node when key is an empty string.
Support for Python 2.7 and Python 3.5 was dropped.
Invalid access in struct mode raises Python-consistent exceptions: KeyError for dictionary-style missing-key access and AttributeError for attribute-style missing-attribute access.
Automatic conversion of date strings during YAML decoding is disabled.
Deprecations 4
Direct assignment and typed-container mutation warn when implicitly converting a value to another type; use OmegaConf.update for explicit conversion.
Deprecated in favor of OmegaConf.register_resolver as the canonical custom resolver API.
cfg.select(key) is deprecated in favor of OmegaConf.select(cfg, key).
cfg.update(key, value) is deprecated in favor of OmegaConf.update(cfg, key, value).
New APIs and options 20
Can validate runtime arguments and return values against annotations using off, warn, or error policies; the default is advisory warnings.
DictConfig supports | for a new merged config and |= for an in-place merge; ListConfig does not support these operators.
Explicitly converts values using OmegaConf primitive node types before destination validation.
Checks whether a select-style key path can produce a value without returning a default or raising.
Compares configs by unresolved container structure.
Accepts default_flow_style to control YAML collection flow style.
Provides explicit container typing for disambiguating assignments to unions of typed container types.
Structured config types can be union members, selected by type, with ambiguous mappings handled explicitly.
Structured configs support unions of typed container types, with explicit container typing available for ambiguous assignments.
Structured configs support Literal annotations, including Literal members of unions.
ListConfig implements typing.MutableSequence.
Tests whether an object is an OmegaConf object.
Tests whether an object is an OmegaConf dict.
Queries whether a node is an interpolation.
Tests whether an object is an OmegaConf list.
Tests whether a config key or node is missing, with value '???'.
Queries whether a node represents None.
Queries whether a config node is optional and can take None.
Config files can be loaded and saved using pathlib.Path objects.
Structured Configs let you create OmegaConf objects from dataclasses, attr classes, or objects; OmegaConf retains type information and validates config mutations.
Performance 2
Uses yaml.CDumper instead of yaml.Dumper whenever possible to speed up dumping.
Uses yaml.CSafeLoader instead of yaml.SafeLoader whenever possible to speed up parsing.
Behavior and default changes 11
Supported in Union annotations; transparent PEP 695 type aliases are also supported.
Escaped literal ??? values are supported across interpolation, resolvers, and YAML; plain ??? returned by a resolver is missing on access.
Key paths in update, select, from_dotlist, and from_cli support backslash escaping for literal dots, brackets, and equals signs.
Missing-key errors suggest similar key names when any exist.
Can address keys containing literal dots, brackets, colons, or backslashes.
Undeprecated as the canonical custom resolver API; register_new_resolver and legacy_register_resolver are deprecated.
Structured configs accept string-valued enum assignments using either the enum member name or its value.
Structured configs can inherit from Dict, allowing arbitrary fields.
DictConfig implements typing.MutableMapping.
Enums can now be used as config values and keys.
Exception messages are standardized.
Fixes and other changes 18
Iteration over List[Union[...]] yields selected concrete values rather than UnionNode wrappers, matching indexing.
Negative list-index interpolations and negative slicing edge cases now behave more like Python lists.
Follows Python list semantics for negative and out-of-range indices and leaves the list unchanged when validation fails.
Supports collections.OrderedDict as both a top-level input and a nested value.
Works with nested readonly structured configs and no longer fails when merging into a null dictionary root, including optional Structured Config fields.
Adds a resolve_custom_resolvers flag to opt into custom resolver evaluation while handling missing values dereferenced by interpolations.
No longer raises UnsupportedValueType when a custom resolver returns a dict or list.
Resolves nested interpolations in resolver-returned containers in one call, including when another field refers to the container before its field is visited.
Integer interpolation segments and integer-looking string paths can resolve integer dictionary keys; configurations reject ambiguous pairs such as 1 and "1".
Returns the provided default when a relative key climbs above the config root.
With resolve=True, each custom resolver is evaluated at most once per conversion pass, matching OmegaConf.resolve behavior for these cases.
No longer crashes when merging structured configs containing union types.
Follows intermediate node interpolations to existing config containers, applying nested updates to the referenced container while preserving the interpolation.
Fixes source installs with setuptools versions that no longer provide pkg_resources.
pretty() handles strings containing Unicode characters correctly.
Accessing a config in struct mode with get() and a None default no longer raises AttributeError.
Equality no longer fails when an object contains unresolvable values.
Indirect access to a missing value correctly raises MissingMandatoryValue.