# omegaconf: one Python config API over YAML, dataclasses and CLI overrides

> A hierarchical configuration library that reads YAML, merges it with dataclass-backed structured configs and command line arguments, and hands back the same object type no matter where a value came from.

**hydra-ecosystem/omegaconf** — Flexible Python configuration system. The last one you will ever need.

- Repository: https://github.com/hydra-ecosystem/omegaconf
- Website: https://hydra-ecosystem.github.io/omegaconf/
- Stars: 2,434 · Forks: 160
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/hydra-ecosystem-omegaconf

## Merging YAML, dataclasses and CLI arguments behind one API

The problem OmegaConf addresses is not reading YAML. Python has done that for years. The problem is what happens after reading: a dataclass default gets overridden by a YAML file, the YAML file gets overridden by a command line flag, and every one of those sources hands back a different kind of object. Code written against a plain dict ends up with dicts in some branches and dataclass instances in others, and the type checker gives up somewhere in the middle.

The README describes OmegaConf as a hierarchical configuration system with support for merging configurations from multiple sources, specifically YAML config files, dataclasses or objects, and CLI arguments, and it makes one promise: a consistent API regardless of how the configuration was created. That promise is the whole design. A merged configuration is still a single tree you can index, nest and interpolate, and reading a key does not require knowing which layer it came from.

The repository topics match that framing: configuration-files, configuration-loader, schema-validator and python-types sit alongside the plain python and yaml tags. The schema-validator tag is the interesting one, because it points at the structured config feature rather than at generic YAML parsing. Having your dataclass annotations act as a schema is what turns a config file from an untyped blob into something that can fail early with a message naming the field.

## Installing the stable 2.3 line or the 2.4.0.dev pre-release

The README gives two install paths and they are not equivalent. The stable branch is 2.3, and 2.3.1 is the current stable release, published on 2026-06-11:

```bash
pip install --upgrade omegaconf
```

The development line is 2.4.0.dev, and the README gives its own command so that pre-release traffic stays separate from stable installs:

```bash
pip install --upgrade --pre omegaconf
```

The repository's pyproject.toml records the in-development version as 2.4.0.dev16, which tells you the pre-release has been iterating for a while rather than sitting at an early dev0. Both lines come from the same tree, and the README documents each one against its own branch so the docs for a pre-release do not drift away from what you installed.

One more detail worth catching before you install: the project moved. The README opens with a notice that OmegaConf moved from the omry GitHub account to hydra-ecosystem, and that the repository moved with its history, issues and pull requests intact. The licence is unchanged at BSD 3-Clause, and the README states no action is required from users, but contributors should send new issues and pull requests to the new home. Old tutorials that link to the omry path will still resolve, and the package name on PyPI does not change.

## Structured configs turning field annotations into a schema

This is where OmegaConf earns its keep over the standard library. Mark a dataclass and OmegaConf uses its type annotations to build a typed node for each field, so a typo in a YAML key becomes an error naming the field rather than a KeyError three modules away, and a wrong type is caught at merge time.

The release history shows this area getting the most attention. Version 2.3.0 added inspection of metadata on structured config fields, so a field whose metadata sets `omegaconf_ignore` to `True` is skipped entirely, which is how you keep a field that exists on the dataclass for type checking out of the config surface. That same release added support for interpolating to keys that contain a non-leading dash, and fixed a case where merging nested structured configs could incorrectly raise an exception.

That last fix deserves a second look if you merge configs at runtime. A bug that makes a legitimate merge throw is the worst shape of bug in a config library, because the failure looks like your data is wrong when the library is. Version 2.2.3, published 2022-08-18, is a good illustration of the smaller correctness work that dominates real releases: sliced assignment on a list config no longer leaves partial updates behind when it errors, a crash on attr classes whose field annotations contain forward references was fixed, and the error message for illegal type annotations such as `typing.Sequence` got clearer. It also reverted an accidental behaviour change that had disallowed implicit conversion from `Path` to `str`.

## Grammar generation and vendored dependencies in the build

The repository tree shows an unusual amount of build machinery for a library this small. There is a `build_helpers/` directory, a `noxfile.py`, and a `.pre-commit-config.yaml`. The setup.py imports five custom commands from build_helpers, including ANTLRCommand, which is a strong hint about where the interpolation grammar comes from: OmegaConf generates parser code rather than hand-writing it.

The pyproject.toml confirms the split. The `omegaconf/grammar/gen` directory is excluded from linting because it is generated, and `omegaconf/vendor` is excluded for the same reason, which means third party code is committed into the tree rather than installed as a dependency. setup.py walks `omegaconf/vendor` with os.walk and turns every directory into a package name, so a vendored dependency ships inside the wheel.

The practical consequence is that `pip install omegaconf` needs no compilation step and no system packages, which is a real advantage in a container or on a locked down host. The other consequence is that the wheel is larger than the import graph suggests, and that a project shipping a parser generator in its build tooling is not going to be trivial to fork. Tooling choices are strict here: ruff enforces an 88 character line length and targets py310, and pytest runs with `--import-mode=append -Werror`, so warnings are failures rather than noise.

## A debugger plugin and a release cadence worth reading

The repository lists one optional subproject, `omegaconf-pydevd`, described as a pydevd debugger plugin for inspecting OmegaConf objects in supported debuggers. It lives under `subprojects/` and carries its own version file in the bumpversion configuration, so it is versioned separately from the library. That is a good sign about how seriously the project treats it, and it is also the fastest way to see the object model from the inside, since a config tree shows its merged state rather than the layers underneath.

On cadence, the release list is uneven in a way worth understanding rather than judging. Version 2.2.3 landed 2022-08-18 and 2.3.0 followed on 2022-12-08, both adding Python 3.11 support among other things. Then nothing released for over three years until 2.3.1 on 2026-06-11, which contained a single bug fix for source installs against setuptools versions that no longer ship pkg_resources. Meanwhile the last push was on 2026-09-28 and the pre-release counter is at dev16, so work is landing on main as development builds rather than as numbered releases.

If you pin a version in production, the practical reading is that 2.3.0 and 2.3.1 are the only stable tags that matter right now, and that the development line is where new work is. Changelog fragments live in `news/` and are assembled by towncrier into NEWS.md using a template at `news/_template.rst`, which is why individual commits do not carry release note text.

## Where the README ends and the external docs begin

The README is short by design, and short in an informative way. It names the problem, states the consistent API promise, points at the pydevd subproject, and gives the two install commands with links to the stable and development documentation. Everything else is one hop away: the documentation status badge points at the 2.3 branch docs, the tutorial notebook is available on Binder, and there is a Zulip chat linked for support.

That structure matters for evaluation. If you are comparing OmegaConf with Hydra itself, the related searches people type are OmegaConf versus Hydra and OmegaConf alternatives, and the answer is largely in the relationship rather than in a feature table. Hydra is the application framework built on top of this library, so they are not substitutes; OmegaConf is the config object and merge machinery, and Hydra adds command line composition, config groups and directory layout on top. Reading the README alone will not settle that question, because the README does not discuss it.

Two things to check against the external documentation before committing: the exact YAML and interpolation syntax, which lives in the docs and not the README, and the supported Python range. The README badge claims Python 3.10 through 3.14, which is a wider range than the 2.3.0 release notes, from 2022, would have been tested against, so read the current docs rather than assuming the badge describes the release you get from pip.

## Conclusion

omegaconf is at its best when configuration has to be assembled from more than one place, which is the normal case for anything with a YAML file, a dataclass and a handful of command line switches, and where an interpolation mistake should raise at load time instead of three hours into a training run. It is the wrong tool if you want a config language with richer logic than YAML plus overrides, or if a plain dict is all your program needs. Verify two things first: that your Python version is inside the supported range the README lists, and whether the 2.3.0 behaviour on structured config merging matches how you merge today, because that bug fix is the one with the widest blast radius.

## FAQ

### What is OmegaConf in Python?

It is a hierarchical configuration system for Python that merges configuration from multiple sources, including YAML files, dataclasses or objects and command line arguments, and exposes a consistent API no matter which source a value came from. Merged configurations stay navigable and interpolable instead of degrading into plain dictionaries.

### How do I install OmegaConf, and which version do I get?

The README gives two commands. `pip install --upgrade omegaconf` installs the stable 2.3 line, currently 2.3.1. `pip install --upgrade --pre omegaconf` installs the development line, which pyproject.toml records as 2.4.0.dev16.

### Is OmegaConf the same thing as Hydra?

No, they sit at different layers. Hydra is the application framework that uses OmegaConf, adding command line composition, config groups and experiment directory layout. OmegaConf is the config object and merge machinery underneath, usable on its own if you only need typed, mergeable configuration.

### What licence is OmegaConf released under?

BSD 3-Clause, and the README states explicitly that the licence did not change when the project moved from the omry account to the hydra-ecosystem organisation. The move carried history, issues and pull requests with it, and users were told no action is required.

## Sources

- [hydra-ecosystem/omegaconf on GitHub](https://github.com/hydra-ecosystem/omegaconf)
- [License: BSD-3-Clause](https://github.com/hydra-ecosystem/omegaconf/blob/main/LICENSE)
- [Project website](https://hydra-ecosystem.github.io/omegaconf/)
- [README](https://github.com/hydra-ecosystem/omegaconf/blob/main/README.md)
- [Releases](https://github.com/hydra-ecosystem/omegaconf/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hydra-ecosystem-omegaconf