Skip to content

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 imported config before calling os.getenv(). The import triggers load_dotenv().
  • .env not found — The file must be in the project root (next to pyproject.toml). load_dotenv() searches from the config.py location upward.
  • Wrong value returned — Variable names are case-sensitive. DB_USER and db_user are 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.