Getting started

Installing

Install omniconf from PyPi using your favorite package manager:

$ pip install omniconf
$ uv add omniconf

Certain configuration backends have extra dependencies, you can install them using the extras syntax:

$ pip install 'omniconf[toml,yaml]'
$ uv add 'omniconf[toml,yaml]'

omniconf has no dependencies of its own, and supports all currently supported Python versions.

If you need support for older Python versions, see the table below. Additionally, PyPy is not formally supported but is automatically tested using CI, usually the PyPy version that tracks the latest two Python versions.

Python version	Support added	Support removed
3.15	1.6.0
3.14	1.6.0
3.13	1.6.0
3.12	1.5.0
3.11	1.5.0
3.10	1.5.0	1.6.0
3.9	1.5.0	1.6.0
3.8	1.3.1	1.6.0
3.7	1.0	1.5.0
3.6	1.0	1.5.0
3.5	1.0	1.5.0
3.4	1.0	1.4.0
3.3	1.0	1.3.0
2.7	1.0	1.5.0
Jython	1.0	1.4.0

Choosing a configuration approach

omniconf supports two main methods of defining settings and using the loaded values.

If you have no preference, or have never used omniconf before, try the Typed registry approach approach first.

Functional

Added in version 1.0.

The functional approach is suitable for most situations (and was the only way before omniconf 2.0.0), but behaves poorly when you want proper typing support or re-use settings between libraries.

See Type annotations for more details, especially the requirements and limitations.

See Functional approach for examples.

Typed registries

Added in version 2.0.0.

A more modern approach inspired by sqlalchemy and Pydantic, typed registries allow better typing support and compositing. Registries can be nested, and support all features of the functional approach. Nested registries are their own type, and values can be used by accessing its attributes, or the whole registry can be passed around as value.

See Typed registry approach for examples.