Skip to main content
Version: 2.4 (prerelease)

Upgrade from 2.3 to 2.4

OmegaConf 2.4 is a prerelease. It is the first feature release since 2.3 and adds richer structured config types, tuple configs, and improvements to interpolation, resolvers, merging, and validation. Read the full 2.4.0rc1 release notes for the complete change list.

Compatibility checklist​

  1. Python: 2.4 requires Python 3.10 or newer. Check the interpreter used by both your application and CI.
  2. Tuples: native tuples now create immutable TupleConfig values rather than mutable ListConfig values. Review mutation and sequence-type checks in the tuple migration guide.
  3. Implicit conversion: assignment and typed-container mutation still convert compatible values, but emit FutureWarning. Assign the declared type directly or use OmegaConf.update() for explicit conversion.
  4. Missing text: ??? remains the missing marker. To store literal ???, write \???. A resolver returning plain ??? now produces a missing value. See missing values.
  5. Resolver registration: OmegaConf.register_resolver() is the canonical API. The older register_new_resolver() and legacy_register_resolver() methods are deprecated.
  6. OmegaConf.create(None): 2.3 returned a DictConfig wrapping None; 2.4 returns literal None. Handle or check None directly instead of relying on config-container behavior.
  7. Resolving missing interpolations: In 2.4, OmegaConf.resolve() raises InterpolationToMissingValueError when an interpolation targets ???. Populate the missing value before resolving, or leave the interpolation lazy until it can be satisfied.

New capabilities to consider​

Structured configs accept Literal[...], unions of typed containers, unions of structured config types, and tuple annotations. OmegaConf.typed_list() and OmegaConf.typed_dict() let you select an otherwise ambiguous union branch explicitly. oc.coerce converts a resolver value to a requested primitive node type. OmegaConf.can_select() checks whether a key path can produce a value, and OmegaConf.structural_equality() compares unresolved config structure.

Review the compatibility checklist for affected callers, then adopt new features where they simplify a real use case.