# What changed in omegaconf

> 78 changes in omegaconf 2 from its official release notes, upgrade guides and advisories: 23 breaking, 4 deprecations, 20 new APIs and options. Each one cited. Sources checked 2026-11-13. HTML: https://unstale.sh/pypi/omegaconf/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## omegaconf 2

### Breaking changes

- DictConfig and ListConfig are unhashable and cannot be used as dictionary keys or set elements. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- OmegaConf.create(None) returns literal None instead of a DictConfig(None) wrapper. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Returns NoneType for OmegaConf nodes containing None and validates None/NoneType annotations. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Use is_tuple for tuple-specific behavior; is_sequence accepts either sequence type. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Raises InterpolationToMissingValueError when an interpolation dereferences to a missing value instead of silently overwriting the node with ???. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Raises ConfigTypeError with a clear message when navigating through a structured Optional node that is None, rather than AssertionError. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Integer interpolation segments and integer-looking string paths can resolve integer dictionary keys; configurations reject ambiguous pairs such as 1 and "1". (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Python 3.10 or newer is required; support for Python 3.6 through 3.9 has been dropped. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Native tuples now create a structurally immutable TupleConfig instead of a mutable ListConfig; tuple semantics are experimental. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Lazy access now validates and converts interpolated values against their destination type, matching eager resolution. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Alias expansion is limited by default to avoid excessive config growth from crafted YAML input, with an environment override for trusted configurations. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- pretty() preserves insertion order by default instead of sorting keys; set sort_keys=True to override. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Deleting an item raises ConfigTypeError when the config is in struct mode. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- pop now returns the underlying value rather than a ValueNode. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- pop() raises ConfigTypeError when the config is in struct mode. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- cfg.save() was removed; use OmegaConf.save(). (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- cfg.to_container() was removed; use OmegaConf.to_container(). (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Merging into a node interpolation now copies the target node by value. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- omegaconf.Config was renamed to omegaconf.Container. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- select(key) returns the root node when key is an empty string. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Support for Python 2.7 and Python 3.5 was dropped. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Invalid access in struct mode raises Python-consistent exceptions: KeyError for dictionary-style missing-key access and AttributeError for attribute-style missing-attribute access. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Automatic conversion of date strings during YAML decoding is disabled. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)

### Deprecations

- Direct assignment and typed-container mutation warn when implicitly converting a value to another type; use OmegaConf.update for explicit conversion. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Deprecated in favor of OmegaConf.register_resolver as the canonical custom resolver API. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- cfg.select(key) is deprecated in favor of OmegaConf.select(cfg, key). (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- cfg.update(key, value) is deprecated in favor of OmegaConf.update(cfg, key, value). (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)

### New APIs and options

- Can validate runtime arguments and return values against annotations using off, warn, or error policies; the default is advisory warnings. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- DictConfig supports | for a new merged config and |= for an in-place merge; ListConfig does not support these operators. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Explicitly converts values using OmegaConf primitive node types before destination validation. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Checks whether a select-style key path can produce a value without returning a default or raising. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Compares configs by unresolved container structure. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Accepts default_flow_style to control YAML collection flow style. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Provides explicit container typing for disambiguating assignments to unions of typed container types. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Structured config types can be union members, selected by type, with ambiguous mappings handled explicitly. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Structured configs support unions of typed container types, with explicit container typing available for ambiguous assignments. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Structured configs support Literal annotations, including Literal members of unions. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- ListConfig implements typing.MutableSequence. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Tests whether an object is an OmegaConf object. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Tests whether an object is an OmegaConf dict. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Queries whether a node is an interpolation. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Tests whether an object is an OmegaConf list. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Tests whether a config key or node is missing, with value '???'. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Queries whether a node represents None. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Queries whether a config node is optional and can take None. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Config files can be loaded and saved using pathlib.Path objects. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Structured Configs let you create OmegaConf objects from dataclasses, attr classes, or objects; OmegaConf retains type information and validates config mutations. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)

### Performance

- Uses yaml.CDumper instead of yaml.Dumper whenever possible to speed up dumping. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Uses yaml.CSafeLoader instead of yaml.SafeLoader whenever possible to speed up parsing. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)

### Behavior and default changes

- Supported in Union annotations; transparent PEP 695 type aliases are also supported. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Escaped literal ??? values are supported across interpolation, resolvers, and YAML; plain ??? returned by a resolver is missing on access. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Key paths in update, select, from_dotlist, and from_cli support backslash escaping for literal dots, brackets, and equals signs. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Missing-key errors suggest similar key names when any exist. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Can address keys containing literal dots, brackets, colons, or backslashes. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Undeprecated as the canonical custom resolver API; register_new_resolver and legacy_register_resolver are deprecated. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Structured configs accept string-valued enum assignments using either the enum member name or its value. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Structured configs can inherit from Dict, allowing arbitrary fields. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- DictConfig implements typing.MutableMapping. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Enums can now be used as config values and keys. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Exception messages are standardized. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)

### Fixes and other changes

- Iteration over List[Union[...]] yields selected concrete values rather than UnionNode wrappers, matching indexing. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Negative list-index interpolations and negative slicing edge cases now behave more like Python lists. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Follows Python list semantics for negative and out-of-range indices and leaves the list unchanged when validation fails. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Supports collections.OrderedDict as both a top-level input and a nested value. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Works with nested readonly structured configs and no longer fails when merging into a null dictionary root, including optional Structured Config fields. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Adds a resolve_custom_resolvers flag to opt into custom resolver evaluation while handling missing values dereferenced by interpolations. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- No longer raises UnsupportedValueType when a custom resolver returns a dict or list. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Resolves nested interpolations in resolver-returned containers in one call, including when another field refers to the container before its field is visited. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Integer interpolation segments and integer-looking string paths can resolve integer dictionary keys; configurations reject ambiguous pairs such as 1 and "1". (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Returns the provided default when a relative key climbs above the config root. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- With resolve=True, each custom resolver is evaluated at most once per conversion pass, matching OmegaConf.resolve behavior for these cases. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- No longer crashes when merging structured configs containing union types. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Follows intermediate node interpolations to existing config containers, applying nested updates to the referenced container while preserving the interpolation. (2.4.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.4.0)
- Fixes source installs with setuptools versions that no longer provide pkg_resources. (2.3.1) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.3.1)
- pretty() handles strings containing Unicode characters correctly. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Accessing a config in struct mode with get() and a None default no longer raises AttributeError. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Equality no longer fails when an object contains unresolvable values. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)
- Indirect access to a missing value correctly raises MissingMandatoryValue. (2.0.0) — [release notes](https://github.com/hydra-ecosystem/omegaconf/releases/tag/v2.0.0)