---
id: lib-layered-config
version: "5.6.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# lib-layered-config — Cross-platform layered configuration loader for Python

License: permissive · Maintenance: active · Downloads: 128.9K/mo

## What it is and what it does

lib_layered_config solves the problem of configuration authorship tracking. When a setting reaches your program through multiple sources—defaults, config files, environment variables, `.env` files—it becomes hard to debug which source won. This library deep-merges configuration from six layers (defaults, app, host, user, dotenv, environment) in a fixed precedence order and returns an immutable Config object that remembers exactly which layer and file each value came from. You can ask for a value and also ask where it came from, collapsing configuration debugging from a guessing game into a lookup.

The library handles cross-platform path discovery (Linux XDG, macOS, Windows), supports configuration profiles (separate trees for test, staging, production), and includes both a Python API and a CLI for reading, deploying, and scaffolding configs. It uses rtoml for fast TOML parsing and supports TOML, JSON, and optional YAML formats. The design keeps secrets out of committed files by letting environment variables and `.env` outrank file-based config, and it provides safe deployment with automatic backups and conflict handling.

Use it for:

- Debug which configuration source set a value by calling config.origin("key.path") instead of tracing through multiple files and environment variables.
- Deploy configuration across test, staging, and production environments by selecting profiles without hand-merging separate environment setups.
- Scaffold and deploy configuration files to Linux, macOS, and Windows machines without hardcoding platform-specific paths like /etc/myapp/.
- Keep secrets out of version control by letting environment variables and .env files override committed config files automatically.
- Use the CLI to inspect, validate, or deploy configuration without writing Python code in deployment scripts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Loads and merges configuration from multiple sources (defaults, files, environment variables) into a single immutable object while tracking where each value came from.

Yes. The package solves a real debugging pain point (configuration provenance) with a clean API, has low install friction, active maintenance, no known vulnerabilities, and a permissive license. It is worth installing if you need to track where configuration values come from or manage multi-layer config across platforms; skip it if your application has simple, single-source configuration.

## Install

pip install lib-layered-config
uv add lib-layered-config
poetry add lib-layered-config

## Installing lib-layered-config

Before you install: Low install friction: pure Python wheel with four runtime dependencies (lib-cli-exit-tools, orjson, rich-click, rtoml). Active maintenance with a release 15 days ago; repository is not archived.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart:

from lib_layered_config import read_config

config = read_config(vendor="mycompany", appname="myapp")
value = config.get("service.timeout")
origin = config.origin("service.timeout")
print(f"Value: {value}, from: {origin}")

Requires Python 3.10 or later.

Verify before relying:

- Whether the library's performance improvements from rtoml are measurable in typical application startup scenarios.
- How the immutability guarantee is enforced at runtime and whether it prevents all forms of accidental mutation.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 128.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

configuration management, layered config loader, environment variable override, config file merging, dotenv and environment, cross-platform config paths, immutable configuration object, config provenance tracking, configuration-management, environment-variables, cross-platform

[View on SkillFed](https://skillfed.io/packages/lib-layered-config) · [View on PyPI](https://pypi.org/project/lib-layered-config/)