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
Metadata
Release files for config-get 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| config_get-1.0.0.tar.gz | 14.7 kB | Without provenance | Details for config_get-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| config_get-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for config_get-1.0.0-py3-none-any.whl |
Total release size: 26.5 kB
Release files / config_get-1.0.0.tar.gz
| Download URL | config_get-1.0.0.tar.gz |
|---|---|
| Size | 14.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54f17830ca899bcab27b891cbf5d931b4b0c0e80565106af719691a33771b6bb
|
|
BLAKE2b-256 checksum How to use checksums |
3b5b1c57ac9df363701a9005344f59326bc25fe869f624816f9ed14050b412b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.4
|
Release files / config_get-1.0.0-py3-none-any.whl
| Download URL | config_get-1.0.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bcace78ea44b24b32a42fbd9ae245d082acdc795f82af74f7211158b8e2d155f
|
|
BLAKE2b-256 checksum How to use checksums |
546edc91a0f7062da659d99f8dddf23b5bdb8cbb9dd2c9eb63c43b764b76b972
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.4
|
Security for config-get 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.