Install & Compatibility
Where this runs
tested against v2.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.292s · 23.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.280s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OmegaConf
✓ from omegaconf import OmegaConf
II
✓ from omegaconf import II
Used for structured config interpolations.
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
Debug
Known issues
breakingIn 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`.fixUpdate code to use `cfg.get('key', default_value)` or `if 'key' in cfg:` / `hasattr(cfg, 'key')` for existence checks, or handle `AttributeError`/`KeyError`. affects: >=2.1.0
breakingAs 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.fixChange calls from `OmegaConf.select(cfg, 'path', 'default')` to `OmegaConf.select(cfg, 'path', default='default')`.
affects: >=2.1.0
gotchaOmegaConf 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.fixUse `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.
affects: All versions
gotchaIn 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.fixIf 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.
affects: 2.2.1 (reverted in 2.2.2, 2.2.3)
gotchaStructured 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.fixUse Python 3.7+ for pickling complex structured configs, or ensure type hints are simple enough for Python 3.6 if pickling is required.
affects: <=2.3.0 (Python 3.6 only)
gotchaThe `???` 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.fixEnsure 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.
affects: All versions
gotchaWhen defining dataclasses for structured configurations, using mutable objects (like instances of custom classes, lists, or dictionaries) as default values for fields will raise a `ValueError: mutable default ... is not allowed`. This is a standard Python dataclass limitation, not specific to OmegaConf, but frequently encountered when defining structured configs.fixUse `default_factory` for mutable default values in dataclasses. For example, instead of `field: MyClass = MyClass()`, use `field: MyClass = field(default_factory=MyClass)`.
affects: All versions (standard Python dataclass behavior)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'omegaconf'
The `omegaconf` package is not installed in the current Python environment or the environment is not correctly activated.
fixEnsure `omegaconf` is installed: `pip install omegaconf` or `pip install omegaconf==2.3.0` for a specific version. If using a virtual environment, make sure it's activated.
omegaconf.errors.ConfigAttributeError: Key 'some_key' is not in struct
This error occurs when attempting to access or set a key that is not predefined in a structured config (dataclass/attrs) or when the 'struct' flag is enabled on a DictConfig, which prevents adding new keys dynamically.
fixIf using a structured config, define 'some_key' in your dataclass/attrs schema. If dynamically adding keys to a regular DictConfig that has the 'struct' flag enabled, you can temporarily disable it using `with omegaconf.open_dict(cfg): cfg.some_key = value` or `OmegaConf.set_struct(cfg, False)`.
omegaconf.errors.ConfigTypeError: Cannot merge DictConfig with ListConfig
This error arises when attempting to merge two `OmegaConf` objects with incompatible types, specifically trying to merge a dictionary-like configuration (`DictConfig`) into a list-like configuration (`ListConfig`) or vice-versa at the same path.
fixEnsure the structure of the configurations being merged is compatible. If a schema expects a list, the input config at that path must also be a list, not a dictionary, and vice-versa. Adjust either the schema or the input configuration to match types.
omegaconf.errors.MissingMandatoryValue: Missing mandatory value: some_key
A field in a structured config was declared with `MISSING` (e.g., `some_key: int = MISSING`) but was accessed before a value was provided for it.
fixProvide a value for the mandatory key 'some_key' either in your configuration file, through command-line arguments, or by programmatic assignment before attempting to access it.
omegaconf.errors.InterpolationValidationError: Value 'string_value' could not be converted to Integer
This error occurs in structured configs when an interpolated value, resolved from another part of the config or a resolver, cannot be converted to the Python type annotation specified for that field (e.g., trying to assign a string 'hello' to an `int` field).
fixEnsure that the value being interpolated is compatible with the target field's type. If the interpolated value is a string that represents a number, it will be automatically converted. If it's a non-numeric string, the type annotation of the target field should be `str`.
Upgrade
Version history
2.3.1latest on PyPI · released Jun 11, 2026
Audit
Dependencies
PyYAMLrequiredCore functionality relies on YAML processing. Mentioned as a dependency in older versions and implicitly required for YAML-based configs.
dataclassesoptionalRequired for Python 3.6 users when using Structured Configs based on dataclasses.
attrsoptionalAlternative to dataclasses for Structured Configs if using `@attr.s`.