30초 요약
.env는 컨테이너에 그대로 들어가는 파일이 아니다.compose.yaml안의${VAR}를 채우는 파일이고, 컨테이너 환경변수는environment·env_file·docker compose run -e가 따로 정한다. 두 단계를 나눠 보면 값이 어디서 왔는지 찾을 수 있다.${VAR}를 채울 때는 셸 환경변수,--env-file, 프로젝트 폴더의.env순으로 앞선 것이 쓰인다.- 컨테이너 안에서는
docker compose run -e,environment,env_file, 이미지의ENV순으로 앞선 것이 쓰인다. - 어떤 값이 쓰이는지는
docker compose config로 확인한다.
증상/목표
.env에 값을 적었는데 컨테이너 안에서 printenv로 보면 없거나, 예상과 다른 값이 나온다. 셸에서 export해 둔 값이 .env를 덮는 경우도 있다. 어느 파일이 이기는지 정리해 두면 이런 상황에서 원인을 바로 좁힐 수 있다.
원인
.env와 컨테이너 환경변수는 서로 다른 단계에서 쓰인다.
1단계, 보간. Compose는 프로젝트 폴더(보통 compose.yaml이 있는 폴더)의 .env를 읽어 파일 안의 ${VAR}를 치환한다. 같은 변수가 여러 곳에 있으면 셸 환경변수, --env-file로 준 파일, .env 순으로 앞선 것이 쓰인다.
2단계, 컨테이너 환경변수. 치환이 끝난 compose.yaml의 environment와 env_file이 컨테이너에 들어간다. 높은 쪽부터 docker compose run -e, environment(또는 env_file) 안에서 셸 값으로 보간한 것, environment만 쓴 것, env_file, 이미지의 ENV 지시어 순이다. Dockerfile의 ARG·ENV는 Compose 쪽에 같은 항목이 없을 때만 평가된다. environment로 시간대(TZ)를 넣는 실제 예는 Docker 컨테이너 시간대 KST로 맞추기: TZ 환경변수와 tzdata에 있다.
즉 .env에만 적은 변수는 compose.yaml이 ${VAR}로 가져가지 않으면 컨테이너에 들어가지 않는다.
컨테이너 환경변수는 위에 있을수록 앞선다
- 위: 높은 쪽
- 1. docker compose run -e — 실행할 때 준 값이 가장 앞선다
- 2. environment — env_file과 겹치면 environment가 이긴다
- 3. env_file — environment에 없는 변수에 쓰인다
- 4. 이미지의 ENV — Compose 쪽에 같은 항목이 없을 때만
해결 방법
1. 예제 파일 만들기
아래 파일을 한 폴더에 만든다. .env의 ONLY_IN_DOTENV는 compose.yaml이 참조하지 않는 변수다.
services: app: image: alpine:3.20 env_file: - app.env environment: MODE: from-environment GREETING: ${GREETING:-fallback}printf 'GREETING=from-dotenv\nONLY_IN_DOTENV=yes\n' > .envprintf 'GREETING=from-other\n' > other.envprintf 'MODE=from-env-file\nMSG=from-env-file\n' > app.env2. 보간 결과를 config로 확인하기
docker compose config는 치환이 끝난 compose.yaml을 출력한다. .env의 GREETING 값이 들어간다.
docker compose config | grep GREETING셸에서 같은 이름을 주면 .env보다 앞선다.
GREETING=from-shell docker compose config | grep GREETING--env-file을 쓰면 기본 .env 대신 그 파일을 읽는다. 여러 번 줄 수 있고 뒤에 준 파일이 앞 파일을 덮는다.
docker compose --env-file other.env config | grep GREETINGCompose가 실제로 쓰는 변수 값은 docker compose config --environment로 볼 수 있다.
3. 컨테이너 안의 값 확인하기
environment와 env_file에 같은 변수가 있으면 environment가 이긴다. environment에 없는 변수는 env_file 값이 쓰인다.
docker compose run --rm -T app printenv MODE # from-environmentdocker compose run --rm -T app printenv MSG # from-env-fileONLY_IN_DOTENV는 environment에도 env_file에도 없으므로 컨테이너에 없다. 컨테이너에서 쓰려면 environment에 ONLY_IN_DOTENV: ${ONLY_IN_DOTENV}를 적거나 env_file로 읽는다.
일회성으로 덮을 때는 -e가 가장 앞선다.
docker compose run --rm -T -e MODE=from-cli app printenv MODE # from-cli4. 빠진 값은 기본값·필수 표시로 잡기
${VAR}는 값이 없으면 빈 문자열이 된다. 이미지 태그 자리에 쓰면 postgres:처럼 잘못된 값이 만들어진다. 기본값은 ${VAR:-default}, 필수 표시는 ${VAR:?메시지}로 쓴다.
services: db: image: alpine:3.20 environment: DB_PASS: ${DB_PASS:?DB_PASS를 .env에 적어야 한다}확인
아래는 GitHub Actions 러너(ubuntu-latest)에서 verify.sh가 위 예제를 그대로 실행한 결과다. 필수 변수가 없을 때 config가 멈추는 것을 먼저 재현하고, .env에 적은 뒤 통과하는 것을 확인했다.
검증 범위: .env·--env-file·셸 값의 보간 우선순위와 environment·env_file·run -e의 컨테이너 값은 실행으로 확인했다. 이미지 ENV가 가장 낮다는 점과 environment 안에서 셸 값으로 보간한 항목의 순위는 공식 문서로 대조했다.
검증 환경 3항목
| OS | Ubuntu 24.04.5 |
|---|---|
| Docker | 28.0.4 |
| 실행 날짜 | 2026-10-30 |
Docker Compose version v2.38.2
[PASS] docker compose 플러그인이 있다
docker.io/library/alpine:3.20
[PASS] alpine:3.20 이미지를 받았다
[단계 1] .env는 compose.yaml 안의 ${VAR}를 채운다
[PASS] .env 값 GREETING이 compose.yaml에 들어간다
[PASS] 셸 환경변수가 .env보다 앞선다
[PASS] --env-file이 기본 .env 대신 읽힌다
[PASS] --env-file을 쓰면 .env 값은 쓰이지 않는다
[PASS] docker compose config --environment가 쓰인 값을 보여 준다
[단계 2] 컨테이너 환경변수는 environment·env_file·run -e로 정해진다
[PASS] environment에 적지 않은 .env 변수는 컨테이너에 없다
[PASS] environment가 env_file보다 앞선다 (MODE)
[PASS] environment에 없는 변수는 env_file 값이 쓰인다 (MSG)
[PASS] compose.yaml이 참조한 .env 값은 컨테이너에 들어간다 (GREETING)
[PASS] docker compose run -e가 environment보다 앞선다[XFAIL] 필수 변수가 비어 있으면 config가 멈춘다 — 예상된 실패 재현됨 (/required variable DB_PASS is missing a value/)
> error while interpolating services.db.environment.DB_PASS: required variable DB_PASS is missing a value: DB_PASS를 .env에 적어야 한다[PASS] .env에 DB_PASS를 적으면 config가 통과한다
주의
.env에 비밀번호를 적고.gitignore에 넣지 않으면 저장소 이력에 그대로 남는다..env는.gitignore에 넣고, 예시용.env.example만 올린다.- 셸에 같은 이름의 변수가
export돼 있으면.env수정이 반영되지 않는다. 값이 안 바뀌면docker compose config --environment로 먼저 본다. .env는 프로젝트 폴더에서 찾는다.--project-directory가 없으면 첫 번째-f파일이 있는 폴더,-f도 없으면 현재 폴더다. 엉뚱한 폴더를 기준으로 잡으면 읽히지 않으니--env-file로 경로를 준다.
자주 묻는 질문
.env 대신 다른 파일 이름을 쓰려면?
docker compose --env-file 파일이름 up처럼 준다. 이 옵션은 기본 .env 조회를 대신하며, 파일은 작업 폴더 기준 어디에 있어도 된다. --env-file을 여러 번 주면 뒤 파일이 앞 파일을 덮는다.
${VAR:-default}와 ${VAR-default}는 뭐가 다른가?
:-는 변수가 없거나 비어 있으면 기본값을 쓴다. -는 변수가 없을 때만 기본값을 쓰고, 빈 값으로 설정돼 있으면 빈 값을 그대로 쓴다. :?와 ?도 같은 차이로 필수 검사를 한다.