config-get

Cross-platform configuration file locator and reader for Python.

config-get automatically discovers and reads configuration files from standard OS-specific locations. Supports .env, .ini, .toml, .json, .yml, and .yaml formats — no manual path wrangling required.

---

Features

• 🔍 Auto-discovery — searches platform-standard directories (%APPDATA%, ~/.config, etc.)
• 📄 Multi-format — .env, .ini, .toml, .json, .yml/.yaml
• 🪟 Cross-platform — Windows, Linux, macOS
• 🔗 Zero required deps — optional extras for TOML, YAML, dotenv
• 🐍 Pythonic API — dict-like access, context manager, class methods
• 🔄 Reload support — re-read config from disk at any time

---

Installation

pip install config-get

With optional format support:

pip install "config-get[all]"     # all formats
pip install "config-get[envdot]"  # envdot
pip install "config-get[toml]"    # toml (Python < 3.11)
pip install "config-get[yaml]"    # pyyaml

---

Quick Start

from config_get import ConfigGet

# Auto-discover a config file for "myapp" in ~/.config/myapp/
cfg = ConfigGet("myapp", config_dir="myapp")

# Access values
db_host = cfg.get("DB_HOST", fallback="localhost")
api_key = cfg["API_KEY"]

# Section-aware access (for .ini / .toml / nested JSON/YAML)
port = cfg.get("server", "port", fallback="8080")

# Dict-like
for key, value in cfg.items():
    print(f"{key} = {value}")

---

Search Order

Windows

Priority	Path
1	%APPDATA%\<config_dir>\
2	%USERPROFILE%\<config_dir>\
3	%APPDATA%\
4	%USERPROFILE%\
5	Current working directory

Linux / macOS

Priority	Path
1	~/<config_dir>/
2	~/.config/<config_dir>/
3	~/.config/
4	~/
5	Current working directory

For each directory, the following filenames are checked (in order): .env → <stem>.ini → <stem>.toml → <stem>.json → <stem>.yml → <stem>.yaml

Or you can specify your configuration name

---

API Reference

ConfigGet(config_file, config_dir, *, auto_load, create)

cfg = ConfigGet(
    config_file="myapp",   # base filename (stem)
    config_dir="myapp",    # app sub-directory
    auto_load=True,        # load on init (default True)
    create=False,          # create empty .env if not found
)

Class methods

ConfigGet.from_file("path/to/config.toml")   # explicit path
ConfigGet.from_env(config_dir="myapp")        # .env shortcut
ConfigGet.from_ini("myapp", config_dir="myapp")
ConfigGet.from_toml("myapp", config_dir="myapp")
ConfigGet.from_json("myapp", config_dir="myapp")
ConfigGet.from_yaml("myapp", config_dir="myapp")
ConfigGet.search_paths("myapp", "myapp")      # inspect candidate paths

Instance methods

Method	Description
cfg.get(key, fallback=None)	Flat key lookup
cfg.get(section, key, fallback=None)	Section + key lookup
cfg.get_section(section)	Return entire section dict
cfg.all()	Return copy of all data
cfg.reload()	Re-read from disk
cfg.find()	Find path without loading
cfg.load(path=None)	(Re)load from path or auto-discover

Dict-like interface

cfg["KEY"]          # raises KeyError if missing
"KEY" in cfg        # membership test
len(cfg)            # number of top-level keys
list(cfg)           # iterate keys
cfg.keys()
cfg.values()
cfg.items()

---

get_config_file(config_file, config_dir, *, create)

Module-level helper — returns the path of the first matching config file, or None.

from config_get import get_config_file

path = get_config_file("myapp", config_dir="myapp")
if path:
    print(f"Found: {path}")

---

Examples

.env file

DB_HOST=localhost
DB_PORT=5432
SECRET_KEY="my-secret"

cfg = ConfigGet.from_file(".env")
print(cfg["DB_HOST"])   # localhost

.ini file

[database]
host = localhost
port = 5432

[server]
debug = true

cfg = ConfigGet.from_file("app.ini")
print(cfg.get("database", "host"))   # localhost
print(cfg.get_section("server"))     # {'debug': 'true'}

.toml file

[database]
host = "localhost"
port = 5432

cfg = ConfigGet.from_file("config.toml")
print(cfg.get("database", "host"))   # localhost

Context manager

with ConfigGet("myapp", config_dir="myapp") as cfg:
    token = cfg.get("API_TOKEN", fallback="")

Debug search paths

paths = ConfigGet.search_paths("myapp", "myapp")
for p in paths:
    print(p)

---

Logging

config-get uses Python's standard logging module under the config_get logger:

import logging
logging.basicConfig(level=logging.DEBUG)

---

License

MIT © Hadi Cahyadi

👤 Author

Hadi Cahyadi

Support me on Patreon