Environment Variables & Configuration¶
The .env File¶
The template includes a .env file for sensitive configuration — API keys, database credentials, and similar. It's already listed in .gitignore, so it won't be committed to version control.
Add your variables to .env in the project root:
# Database Credentials
DB_USER=
DB_PASS=
# API Keys
API_KEY=your_api_key
# Application Settings
LOG_LEVEL=DEBUG
How config.py Loads Environment Variables¶
Importing config anywhere in your project automatically loads .env via load_dotenv(override=True). After that, variables are available through os.getenv():
from {{ project_slug }} import config
import os
username = os.getenv("DB_USER")
api_key = os.getenv("API_KEY", "default_key")
The override=True flag means values in .env take precedence over any existing system environment variables with the same name.
Global Configuration in config.py¶
Beyond environment variables, config.py provides project-wide path constants that keep file references consistent across scripts and notebooks.
Directory constants¶
These are available immediately on import:
PROJ_ROOT # Project root directory
DATA_DIR # data/
RAW_DATA_DIR # data/raw/
INTERIM_DATA_DIR # data/interim/
PROCESSED_DATA_DIR # data/processed/
EXTERNAL_DATA_DIR # data/external/
MODELS_DIR # models/
REPORTS_DIR # reports/
FIGURES_DIR # reports/figures/
File configuration¶
The template includes a dedicated section for project-wide file paths and constants — look for the # Add global configs here comment in config.py:
# ---------- FILE CONFIGURATION -----------
# Add global configs here for use in your project
RAW_DATASET_FILE = RAW_DATA_DIR / "dataset.csv"
PROCESSED_DATASET_FILE = PROCESSED_DATA_DIR / "dataset.csv"
Add your own file paths and constants here. This gives you a single place to manage paths rather than scattering them across scripts.
Importing¶
Import the constants you need directly:
from {{ project_slug }}.config import PROCESSED_DATA_DIR, RAW_DATASET_FILE
df = pd.read_csv(RAW_DATASET_FILE)
df.to_parquet(PROCESSED_DATA_DIR / "cleaned.parquet")
The reload() function¶
When working in notebooks, you may update .env without wanting to restart the kernel. Use reload() to re-run load_dotenv() and pick up changes:
from {{ project_slug }} import config
config.reload() # Re-loads .env, prints PROJ_ROOT to confirm
Troubleshooting¶
- Variables returning
None— Make sure you've importedconfigbefore callingos.getenv(). The import triggersload_dotenv(). .envnot found — The file must be in the project root (next topyproject.toml).load_dotenv()searches from theconfig.pylocation upward.- Wrong value returned — Variable names are case-sensitive.
DB_USERanddb_userare different variables. - Security in notebooks — Avoid printing environment variables (
print(os.getenv("API_KEY"))) in notebooks. If committed, the output cells expose your secrets in version control.