Recommended way to handle .env and .env.local

[Allena101]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

None

Description

I have understood that this template uses .env in different way compared to what is kind of the standard way. Is my understanding correct that we are meant to handle the .env file just for local pushing to the repo? And then also have another .env file (e.g. .env.local) where we would store sensitive info such as api keys or passwords?

Operating System

Linux, Windows

Operating System Details

No response

Project Version

Newest

Python Version

No response

Additional Context

No response

[majidninja]

Almost: the tracked .env is meant to be committed, but only with local development defaults. Real secrets don't go into a second file. They go into environment variables where you deploy.

From development.md:

The tracked .env file contains local development defaults, passwords, and other configuration. [...] Do not store deployment secrets in .env.

How it fits together:

• backend/app/core/config.py loads settings with pydantic-settings using env_file="../.env". Pydantic-settings gives real environment variables priority over the .env file, so anything you export (or set in CI or your host) overrides the changethis defaults without touching the file.
• That's what the deployment guides do. For Docker Compose you export SECRET_KEY=..., POSTGRES_PASSWORD=... and FIRST_SUPERUSER_PASSWORD=... on the server, or store them as GitHub Actions repository secrets for the deploy workflow. For FastAPI Cloud you add them as app secrets.
• There's a safety net. If SECRET_KEY, POSTGRES_PASSWORD or FIRST_SUPERUSER_PASSWORD is still changethis and FASTAPI_ENV isn't development, the settings validator raises an error, so a deploy can't silently use the committed defaults.

If you want a git-ignored file for your own local secrets (say a personal API key while developing), the template doesn't read .env.local out of the box, but it's a small change:

model_config = SettingsConfigDict(
    env_file=("../.env", "../.env.local"),  # later files override earlier ones
    env_ignore_empty=True,
    extra="ignore",
)

Then add .env.local to .gitignore. That covers running the backend directly (fastapi dev / uv run). Docker Compose is different: compose.yml passes an explicit list of variables to the backend container (SECRET_KEY: ${SECRET_KEY:?...} etc.), interpolated from .env and your shell. To override one of those locally, run docker compose --env-file .env --env-file .env.local watch. For a new variable such as an API key, also add a line for it under the backend's environment:.