Loading .env Files in Docker and Compose

A .env file is a local-development convenience, but the moment a Python service is containerized the question changes: does the file travel into the image, get injected as environment variables, or stay on the host? Getting this wrong either leaks secrets into image layers or leaves the container with no configuration at all. This page shows the correct runtime-injection pattern, and how it relates to the .env file management rules and the precedence order.

Problem 1: baking .env into the image

Copying the file into the image is the most common and most dangerous mistake.

# Dockerfile — ANTI-PATTERN
COPY .env /app/.env       # secrets are now in an image layer, forever

Anyone who can pull the image can run docker history and extract the layer. The secret is also immutable — rotating it means rebuilding and redeploying the image.

Problem 2: expecting python-dotenv to run in production

The mirror-image mistake is assuming load_dotenv() does the work everywhere.

# app.py — ANTI-PATTERN in a container
from dotenv import load_dotenv
load_dotenv()             # there is no .env in the container; this loads nothing

In a container the platform injects real environment variables; there is no file to load. Relying on load_dotenv() silently gives you an unconfigured process.

Secure implementation

Inject at runtime with Compose’s env_file, and read os.environ (or a settings model). Keep .env on the host and gitignored.

# config.py — reads injected env vars; .env is a local-only fallback
from pathlib import Path
from dotenv import load_dotenv
from pydantic_settings import BaseSettings, SettingsConfigDict


# In local dev only: load .env WITHOUT overriding real env vars.
load_dotenv(Path(__file__).parent / ".env", override=False)


class Settings(BaseSettings):
    model_config = SettingsConfigDict(extra="forbid")
    database_url: str
    redis_url: str = "redis://localhost:6379/0"


settings = Settings()     # validated from injected env vars in the container

# compose.yaml — inject the host .env as container environment variables
services:
  app:
    build: .
    env_file:
      - .env              # read on the host, injected as env vars; not copied in

The container process reads validated environment variables; the .env file never enters the image.

Gotchas & version-specific behaviour

• Compose env_file does not expand shell variables inside the file — values are literal.
• Values set with environment: in Compose override those from env_file, matching the precedence order.
• docker run --env-file .env behaves like Compose’s env_file; -e KEY=value takes precedence over it.
• override=False matters here: if a stray .env exists in the image build context, it must never win over the injected variable.
• For real secrets, prefer Docker/Swarm secrets or a manager over env_file; env vars are visible to anyone who can docker inspect.

Production parity checklist

• Gitignore .env and ship a .env.example with dummy values.
• Never COPY .env in the Dockerfile; scan image layers for secrets in CI.
• Use env_file (dev) and a secret manager (prod) so the same code reads os.environ in both.
• Load .env with override=False so injected values always win.
• Validate every injected variable through a BaseSettings model at startup.

Key takeaways

Inject configuration into containers at runtime and read it through a validated settings model; never bake a .env into an image. The .env file is a local-dev fallback loaded with override=False, nothing more.