Skip to content

Configuration Internals (defaults and overrides)

This page is for contributors: it explains where Pipelex defaults live, how configuration is merged at runtime, and where to change the behavior in code.

For the user-facing configuration guide, see Configuration Overview.

Mental model (for contributors)

Pipelex configuration is merged in layers:

  • Shipped defaults: maintained by the Pipelex project and used as the baseline by the installed package.
  • Project overrides: created in .pipelex/ by pipelex init … and edited by projects that use Pipelex.
  • Root override files (advanced): optional files for machine/env/run-mode/super overrides.

The key idea: client projects typically edit .pipelex/, while the Pipelex repository holds the default values used as a starting point.

Where defaults live (Pipelex repository)

  • Default values (baseline): repo root pipelex.toml
  • User-facing templates copied into .pipelex/ by the init flow: pipelex/kit/configs/…

Merge order (runtime)

The configuration loading/merging behavior is implemented in pipelex/system/configuration/config_loader.py.

At a high level, the load order is:

  1. Pipelex base defaults (from the installed package)
  2. Project config from .pipelex/pipelex.toml (when running in a client project)
  3. Root overrides (optional), in this order:
  4. pipelex_local.toml
  5. pipelex_{environment}.toml
  6. pipelex_{run_mode}.toml
  7. pipelex_override.toml

Unit test special case

When unit testing, run-mode overrides may be loaded from tests/pipelex_{run_mode}.toml (example: tests/pipelex_unit_test.toml).

Where to change things in code

  • Config merge logic: pipelex/system/configuration/config_loader.py
  • Override lists (local / super): pipelex/system/configuration/config_root.py

Contributor guidelines for config changes

  • If you change defaults, update the repo root pipelex.toml (and consider whether templates in pipelex/kit/configs/… should also be updated).
  • If you change templates, keep them user-focused and stable; avoid adding internal-only details.
  • If you change merge order or override semantics, treat it as a potentially breaking change and document it (changelog + migration notes if needed).