How to Merge Environment-Specific Config JSON in Python

Loads a base JSON config and overlays environment-specific overrides, merging the two dictionaries into one final config.

Easy Python 3.9+ Aug 9, 2026 Files & data 14 views 0 copies

json config pathlib environment merge

Python code

21 lines

Python 3.9+

import json
import pathlib


def load_config(base_path: pathlib.Path, env: str) -> dict:
    base_config = json.loads(base_path.read_text())
    env_path = base_path.with_name(f"config.{env}.json")
    if env_path.exists():
        env_config = json.loads(env_path.read_text())
        return {**base_config, **env_config}
    return base_config


if __name__ == "__main__":
    base = pathlib.Path("config.json")
    base.write_text(json.dumps({"host": "localhost", "port": 8080, "debug": False}))
    env = pathlib.Path("config.prod.json")
    env.write_text(json.dumps({"host": "prod.example.com", "debug": True}))

    merged = load_config(base, "prod")
    print(json.dumps(merged, indent=2))

Output

stdout

{
  "host": "prod.example.com",
  "port": 8080,
  "debug": true
}

How it works

The load_config function reads the base config.json file into a dictionary, then checks for a config.<env>.json file next to it. If the override file exists, it merges the two dicts using dictionary unpacking {**base, **env} so that env-specific values replace base values while preserving keys not present in the override. This relies on the standard library json and pathlib modules, making it portable and dependency-free. The approach is straightforward but only does a shallow merge — nested structures will be replaced rather than deep-merged.

Common mistakes

Using `json.load` instead of `json.loads` when reading text from a file
Hardcoding file paths instead of using `pathlib.Path` for cross-platform compatibility
Assuming nested keys merge instead of being overwritten by the env config

Variations

Use `dict(base_config, **env_config)` as a simpler merge syntax
Implement a recursive deep-merge for nested JSON structures

Real-world use cases

Deploying a web app to staging and production with secrets and hostnames overridden per environment.
Building CLI tools that read user-specific settings merged over defaults.
Managing service orchestration, e.g., merging Kubernetes config maps with environment overrides.

How to Merge Environment-Specific Config JSON in Python

Python code

Output

How it works

Common mistakes

Variations

Real-world use cases

More from Files & data

Tutorials

Quizzes

Python code

Output

How it works

Common mistakes

Variations

Real-world use cases

More from Files & data

Keep learning

Tutorials

Quizzes