OmegaConf

Warnings

• breaking In OmegaConf 2.1, accessing non-existent keys via `DictConfig.__getattr__` (e.g., `cfg.non_existent_key`) now raises an `AttributeError`, and `DictConfig.__getitem__` (e.g., `cfg['non_existent_key']`) raises a `KeyError`. Previously, these operations returned `None`.
  Fix: Update code to use `cfg.get('key', default_value)` or `if 'key' in cfg:` / `hasattr(cfg, 'key')` for existence checks, or handle `AttributeError`/`KeyError`.
• breaking As of OmegaConf 2.1, the `OmegaConf.select()` method requires keyword arguments for all parameters after the `key`. Positional arguments for `default` and `throw_on_missing` are no longer supported.
  Fix: Change calls from `OmegaConf.select(cfg, 'path', 'default')` to `OmegaConf.select(cfg, 'path', default='default')`.
• gotcha OmegaConf objects (`DictConfig`, `ListConfig`) are not native Python `dict` or `list` instances. Direct usage with APIs expecting standard Python containers can lead to unexpected behavior. They also retain OmegaConf's specific features like interpolation and type safety.
  Fix: Use `OmegaConf.to_container(cfg, resolve=True)` to convert an OmegaConf object to a plain Python `dict` or `list`, optionally resolving interpolations during conversion. For structured configs, `OmegaConf.to_object()` can convert to the original dataclass/attrs instance.
• gotcha In OmegaConf 2.2.1, implicit conversion from `pathlib.Path` objects to `str` was disallowed, leading to `ValidationError` when assigning a `Path` to a string-typed structured config field. This behavior was reverted in versions 2.2.2 and 2.2.3, restoring the implicit conversion.
  Fix: If encountering issues in 2.2.1, explicitly cast `Path` to `str` (e.g., `str(my_path)`) or upgrade to 2.2.2+ where the implicit conversion is restored.
• gotcha Structured configs with complex type hints (e.g., nested container types, containers with optional element types) cannot be pickled on Python 3.6 due to limitations in Python's pickling support for such types.
  Fix: Use Python 3.7+ for pickling complex structured configs, or ensure type hints are simple enough for Python 3.6 if pickling is required.
• gotcha The `???` syntax indicates a mandatory value in the configuration. Accessing a mandatory value that has not been set (either directly or via interpolation/CLI overrides) will raise a `MissingMandatoryValue` exception at runtime.
  Fix: Ensure all mandatory `???` values are provided through configuration files, command-line arguments, or environment variables before being accessed. Handle `MissingMandatoryValue` exceptions if dynamic resolution is expected.

Install

• pip install omegaconf Install stable version

Imports

• OmegaConf

  from omegaconf import OmegaConf

• II

  from omegaconf import II

  Used for structured config interpolations.

Quickstart

This quickstart demonstrates how to create configurations from Python dictionaries and YAML strings, access values using dot notation and dictionary-style access, utilize variable interpolation (including environment variables), and create structured configurations using dataclasses for type safety.

from omegaconf import OmegaConf
import os

# Create a config from a dictionary
conf = OmegaConf.create({
    "database": {
        "host": "localhost",
        "port": 5432,
        "user": "${oc.env:DB_USER, default_user}"
    },
    "server": {
        "port": "${database.port}"
    }
})

# Access config values
print(f"Database host: {conf.database.host}")
print(f"Database user: {conf.database.user}") # Resolves from env var or default
print(f"Server port: {conf.server.port}")

# You can also load from YAML strings or files
yaml_string = """
app:
  name: my_app
  version: 1.0
"""
app_conf = OmegaConf.create(yaml_string)
print(f"App name: {app_conf.app.name}")

# Overriding values
conf.database.host = "remote_db"
print(f"Updated database host: {conf.database.host}")

# Example of structured config with dataclasses (requires Python 3.7+ or dataclasses backport for 3.6)
from dataclasses import dataclass

@dataclass
class DatabaseConfig:
    host: str = "127.0.0.1"
    port: int = 5432

@dataclass
class Config:
    db: DatabaseConfig = DatabaseConfig()
    debug: bool = False

structured_conf = OmegaConf.structured(Config)
print(f"Structured config DB host: {structured_conf.db.host}")

# Set an environment variable for testing
os.environ['DB_USER'] = 'my_secret_user'
resolved_user_conf = OmegaConf.create({"db_user": "${oc.env:DB_USER}"})
print(f"Resolved DB user from env: {resolved_user_conf.db_user}")
del os.environ['DB_USER'] # Clean up