OmegaConf Documentation

OmegaConf is a hierarchical configuration system. It allows you to merge configurations from multiple disparate sources into a single, consistent API. Supported sources include:

• YAML configuration files
• Python dataclasses and objects
• Command Line Interface (CLI) arguments

When accessing an interpolated field in a Structured config, OmegaConf validates the value and attempts to convert it to the annotated type. For example, if an int field interpolates a str that contains digits, it will be automatically converted to an integer.

Note: This validation step is currently skipped for container node interpolations (e.g., interpolating an int into a Dict).

from omegaconf import II, OmegaConf
from dataclasses import dataclass

@dataclass
class Interpolation:
    str_key: str = "string"
    int_key: int = II("str_key")

cfg = OmegaConf.structured(Interpolation)

# Accessing cfg.int_key when str_key is 'string' raises InterpolationValidationError
# But if we update the source:
cfg.str_key = "1234"
assert cfg.int_key == 1234  # Automatically converted to int

When securing configuration, choose between readonly and protected based on the required scope and type of protection:

OmegaConf is proposing a general per-node provenance model to allow users to map a configuration node back to its origin. This is intended to support IDE features like 'go to definition', diagnostics, and tracking which merged source 'won' during configuration composition.

Instead of just tracking YAML line/column numbers, the model is designed to be abstract to support various sources including:

• Filesystem: Local YAML files.
• Hydra Sources: Packaged configs, plugin-backed sources, or composed configs.
• Python: Nodes created via OmegaConf.create().
• Synthetic/Merge: Nodes created through operations like merging or manual mutation.

Each node may optionally carry metadata including kind (e.g., file, python, merge), source (path or URI), line, column, and span.

OmegaConf uses an ANTLR-based grammar to parse string expressions, primarily for interpolations. An interpolation string is any string containing the ${ character sequence. These strings can be a single interpolation or a concatenation of multiple fragments (interpolations and regular strings).

Examples of interpolation strings:

• ${foo.bar}
• https://${host}:${port}
• Hello ${name}
• ${a}${oc.env:B}${c}

from omegaconf import OmegaConf

Versioning

Use HandledType.version to track the representation version of a specific type. You must bump this version if to_node() changes its output in a way that breaks compatibility with older stored representations (e.g., renaming fields, changing types, or adding required fields). Adding optional fields with defaults does not require a bump.

Fallbacks

Fallbacks allow a specialized adapter to store a representation that a more general adapter can read.

• Use compatible_versions to provide an exact list of working versions.
• Use compatible_version_range to provide a policy (e.g., " >=3,<5 ").
• The special range "*" explicitly accepts future compatibility risks.
• Note: Fallback is only one level deep; chained fallback is not supported.

OmegaConf supports lazy variable interpolation using the ${} syntax. Interpolations are evaluated when the node is accessed.

Config Node Interpolation: Interpolated values can point to other nodes in the configuration using dot-notation (foo.bar), brackets ([foo][1]), or a mix (foo[1]).

• Absolute Interpolation: ${path.to.node}
• Relative Interpolation: Prefixed with dots. ${..foo} points to the foo sibling of the current node's parent.

Nested Interpolation: You can nest interpolations to dynamically select sub-configs, e.g., ${plans[${selected_plan}]}.

Custom Resolvers: You can add new interpolation types by registering custom functions using OmegaConf.register_resolver(name, function).

When calling to_object() on a configuration containing adapter-derived nodes, OmegaConf prioritizes the adapter's materialization logic over the standard SCMode.INSTANTIATE path. The behavior depends on the node type:

• Scalar adapter node: Returns the stored value directly, as it is already considered the external type.
• Composite adapter node: Calls adapter.from_node(node), which returns the external object (e.g., a class instance) rather than the internal OmegaConf representation (e.g., a DictConfig).

Note: For to_object() to work on adapted nodes, the corresponding adapter must be registered in the current process.

To allow a field to hold a None value, use Python's typing.Optional annotation. Regular fields (without Optional) will raise a ValidationError if you attempt to assign None to them.

from typing import Optional, Dict, List
from omegaconf import OmegaConf
from dataclasses import dataclass, field

@dataclass
class Modifiers:
    num: int = 10
    optional_num: Optional[int] = 10
    optional_dict: Optional[Dict[str, int]] = None
    list_optional: List[Optional[int]] = field(default_factory=lambda: [10, MISSING, None])

conf = OmegaConf.structured(Modifiers)

# This is allowed because of Optional annotation
conf.optional_num = None
assert conf.optional_num is None