자동 실행 검증 A · Ubuntu 24.04 · Docker 28.0.4 · 2026-10-30게시 2026-10-30최종 확인 2026-10-30읽기 5분

docker compose .env 우선순위: 셸·--env-file·environment 정리

docker compose에서 .env 값이 컨테이너에 안 보이거나 다른 값으로 덮일 때, 보간과 컨테이너 환경변수를 나눠 우선순위를 확인하는 방법.

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이 참조하지 않는 변수다.

compose.yaml
services:
app:
image: alpine:3.20
env_file:
- app.env
environment:
MODE: from-environment
GREETING: ${GREETING:-fallback}
Terminal window
printf 'GREETING=from-dotenv\nONLY_IN_DOTENV=yes\n' > .env
printf 'GREETING=from-other\n' > other.env
printf 'MODE=from-env-file\nMSG=from-env-file\n' > app.env

2. 보간 결과를 config로 확인하기

docker compose config는 치환이 끝난 compose.yaml을 출력한다. .env의 GREETING 값이 들어간다.

Terminal window
docker compose config | grep GREETING

셸에서 같은 이름을 주면 .env보다 앞선다.

Terminal window
GREETING=from-shell docker compose config | grep GREETING

--env-file을 쓰면 기본 .env 대신 그 파일을 읽는다. 여러 번 줄 수 있고 뒤에 준 파일이 앞 파일을 덮는다.

Terminal window
docker compose --env-file other.env config | grep GREETING

Compose가 실제로 쓰는 변수 값은 docker compose config --environment로 볼 수 있다.

3. 컨테이너 안의 값 확인하기

environment와 env_file에 같은 변수가 있으면 environment가 이긴다. environment에 없는 변수는 env_file 값이 쓰인다.

Terminal window
docker compose run --rm -T app printenv MODE # from-environment
docker compose run --rm -T app printenv MSG # from-env-file

ONLY_IN_DOTENV는 environment에도 env_file에도 없으므로 컨테이너에 없다. 컨테이너에서 쓰려면 environment에 ONLY_IN_DOTENV: ${ONLY_IN_DOTENV}를 적거나 env_file로 읽는다.

일회성으로 덮을 때는 -e가 가장 앞선다.

Terminal window
docker compose run --rm -T -e MODE=from-cli app printenv MODE # from-cli

4. 빠진 값은 기본값·필수 표시로 잡기

${VAR}는 값이 없으면 빈 문자열이 된다. 이미지 태그 자리에 쓰면 postgres:처럼 잘못된 값이 만들어진다. 기본값은 ${VAR:-default}, 필수 표시는 ${VAR:?메시지}로 쓴다.

compose.required.yaml
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 안에서 셸 값으로 보간한 항목의 순위는 공식 문서로 대조했다.

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 13/13 단계 성공
검증 환경 3항목
OSUbuntu 24.04.5
Docker28.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보다 앞선다
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: DB_PASS가 어디에도 없다
[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에 적어야 한다
수정 후 확인 · 1/1 단계 성공수정 후: .env에 DB_PASS를 적었다
[PASS] .env에 DB_PASS를 적으면 config가 통과한다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • .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}는 뭐가 다른가?

:-는 변수가 없거나 비어 있으면 기본값을 쓴다. -는 변수가 없을 때만 기본값을 쓰고, 빈 값으로 설정돼 있으면 빈 값을 그대로 쓴다. :?와 ?도 같은 차이로 필수 검사를 한다.

참고 자료