Docker Compose 환경변수가 적용되지 않을 때: .env·env_file·environment 우선순위 확인법

Docker Compose 환경변수가 적용되지 않을 때는 .env를 다시 수정하기 전에 변수 치환과 컨테이너 주입을 나눠 확인해야 한다. 셸에 남아 있는 값이 .env보다 먼저 선택되거나, environment에 직접 적은 값이 env_file을 덮어쓰는 경우가 대표적이다. 최종 구성과 실행 중인 컨테이너를 순서대로 확인하면 수정할 위치가 분명해진다.

1. .env와 env_file 차이부터 구분하기

변수 치환은 Compose 파일의 ${변수명}을 실제 값으로 바꾸는 과정이고, 컨테이너 주입은 서비스 안에서 사용할 환경변수를 설정하는 과정이다. .env는 주로 앞 단계에 쓰이며, 서비스의 env_file과 environment는 뒤 단계에 관여한다. 같은 환경변수 파일처럼 보여도 역할이 다르다.

예를 들어 .env에 APP_MODE=development를 적기만 해서는 컨테이너에 APP_MODE가 생기지 않는다. Compose 파일에 environment: APP_MODE: ${APP_MODE}와 같은 연결을 만들거나, 서비스의 env_file로 해당 파일을 지정해야 한다. 호스트 셸에 설정한 변수도 별도 연결 없이 자동 전달되지는 않는다.

또한 docker compose --env-file ./deploy.env up -d의 --env-file은 Compose가 치환에 사용할 입력 파일을 지정한다. 서비스 아래의 env_file: ./app.env는 컨테이너에 전달할 변수를 읽는다. 이름이 비슷하다는 이유로 두 설정을 같은 기능으로 취급하면 엉뚱한 파일을 수정하게 된다.

이 구분의 근거는 Docker 공식 [환경변수 우선순위 문서](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/)다.

📌 핵심 요약

.env 수정이 반영되지 않으면 같은 이름의 셸 변수와 environment 설정부터 확인한다.
config --environment는 치환 입력값, config는 해석된 최종 구성을 보여준다.
최종 구성이 맞아도 기존 컨테이너는 재생성이 필요할 수 있다.

1. .env와 env_file 차이부터 구분하기

Docker Compose 환경변수가 적용되지 않을 때: .env·env_file·environment 우선순위 확인법

2. docker compose config --environment로 적용 경로 확인하기

먼저 배포 명령을 실행하는 터미널에서 Compose 버전을 확인한다. Docker Engine 버전이나 compose.yaml의 version 항목으로 CLI 기능 지원 여부를 판단하면 안 된다. 점검 기록에는 아래 명령이 실제로 출력한 버전 문자열을 남기는 편이 좋다.

docker compose version
docker compose config --environment
docker compose config

이 글의 작성 환경에서는 docker compose version 실행 시 docker 명령을 찾지 못해 설치 버전을 확인하지 못했다. 따라서 특정 버전에서 직접 검증했다고 표기하지 않으며, 아래 결과는 공식 규칙에 따른 예상값이다. 내용은 2026년 10월 22일 확인한 Docker 공식 문서를 기준으로 정리했다.

치환 입력값 확인: docker compose config --environment에서 문제가 되는 변수의 값을 찾는다. .env와 다르다면 먼저 셸에 같은 이름의 변수가 있는지 확인한다.
최종 서비스 구성 확인: docker compose config에서 대상 서비스의 environment를 살핀다. 치환 입력값이 맞아도 직접 지정한 값이나 추가 Compose 파일이 결과를 바꿀 수 있다.
실행 중인 값 확인: 컨테이너가 실행 중이라면 docker compose exec app printenv APP_MODE처럼 대상 변수만 확인한다. 서비스 이름과 컨테이너의 명령 지원 여부에 맞춰 사용한다.

실제 실행에 -f, --env-file, --project-directory를 사용했다면 진단 명령에도 같은 옵션을 넣어야 한다. 다른 디렉터리나 다른 입력 파일로 config를 실행하면 정상처럼 보이는 별도의 구성을 확인할 수 있다.

docker compose --env-file ./deploy.env -f compose.yaml config --environment
docker compose --env-file ./deploy.env -f compose.yaml config

Compose 파일 치환에서는 셸 환경변수가 --env-file의 값보다 우선한다. --env-file을 여러 번 지정하면 뒤에 지정한 파일이 앞선 값을 덮어쓰며, 존재하지 않는 경로는 오류가 된다. 동작과 확인 명령의 근거는 Docker 공식 [변수 치환 문서](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)다.

💡 출력 공유 주의: config --environment에는 치환에 사용하는 비밀값이, config에는 해석된 비밀번호나 토큰이 나타날 수 있다. 터미널 출력 전체를 공개 이슈나 CI 로그에 붙이지 말고, 공유 전 필요한 항목만 추려 값을 가린다. 예제처럼 비밀이 아닌 변수로 재현하면 진단 내용을 공유하기도 쉽다.

2. docker compose config --environmen… 바로가기

3. environment·env_file 우선순위를 최소 예제로 확인하기

다음 예제는 셸, .env, 서비스 env_file, environment에 모두 APP_MODE라는 이름을 사용한다. 파일 3개를 같은 디렉터리에 두고 해당 위치에서 실행하는 조건이다. 셸 명령은 Bash 기준이며 PowerShell에서는 셸 변수 설정과 해제 명령만 바꾸면 된다.

같은 변수명을 사용하는 파일 구성

# .env
APP_MODE=from-dotenv

# app.env
APP_MODE=from-env-file

# compose.yaml
services:
  app:
    image: alpine:3.22
    env_file:
      - ./app.env
    environment:
      APP_MODE: ${APP_MODE}
    command: ["printenv", "APP_MODE"]

이미지의 command는 APP_MODE를 출력하고 종료한다. 실행 중인 서비스가 계속 유지되는 예제가 아니므로, 여기서는 exec 대신 일회성 컨테이너를 만드는 run으로 확인한다. Docker 실행 환경과 이미지 다운로드가 가능한 상태여야 한다.

# Bash
export APP_MODE=from-shell
docker compose config --environment
docker compose run --rm app

# 셸 변수를 해제한 뒤 다시 비교
unset APP_MODE
docker compose run --rm app

PowerShell에서는 $env:APP_MODE = 'from-shell'로 설정하고, Remove-Item Env:APP_MODE로 해제한다. 빈 문자열 대입 대신 변수를 해제해야 .env로 넘어가는 조건을 명확히 비교할 수 있다.

예제에서 바꾼 조건	예상 APP_MODE	값을 결정하는 위치
기본 구성 + 셸 변수 설정	from-shell	셸이 ${APP_MODE} 치환값 제공
기본 구성 + 셸 변수 해제	from-dotenv	.env가 치환값 제공
environment를 APP_MODE: fixed로 변경	fixed	environment의 직접 지정값
environment 블록 제거	from-env-file	서비스의 app.env
environment를 APP_MODE: ""로 변경	空 문자열	명시적인 빈 값이 env_file보다 우선
run --rm -e APP_MODE=from-cli app 실행	from-cli	일회성 실행의 CLI 지정값

각 행은 기본 구성에서 표시한 조건만 바꾼 독립적인 예상 결과다. 특히 run -e의 값은 해당 일회성 컨테이너에 적용되며, 기존 서비스 컨테이너나 Compose 파일을 수정하지 않는다.

운영 진단에서는 변수 이름보다 값이 연결된 경로를 추적하는 편이 정확하다. .env의 APP_MODE를 바꿔도 environment가 fixed라면 결과는 그대로다. 반대로 environment가 ${APP_MODE}라면 Compose 파일보다 셸이나 치환 입력 파일을 먼저 살펴야 한다. 이 분석은 위 예제의 설정 구조와 공식 우선순위 규칙에서 도출된다.

3. environment·env_file 우선순위를 최소 예제로 … 신청하기

4. .env 수정이 반영되지 않을 때 설정 위치별 점검하기

Docker 공식 문서의 컨테이너 환경변수 우선순위는 높은 순서로 아래와 같다. 다만 셸과 .env를 컨테이너 주입원으로 직접 나열하면 오해하기 쉽다. 이 값들은 environment나 env_file과 연결돼야 컨테이너에 영향을 준다.

docker compose run -e로 지정한 값
셸·.env·--env-file의 값을 치환해 environment 또는 env_file로 설정한 값
environment에 직접 지정한 값
서비스 env_file의 값
이미지 Dockerfile의 ENV 값

실제 파일을 고칠 때는 environment에 같은 키가 있는지 먼저 확인한다. 이 항목은 값이 비었거나 미정의 상태여도 env_file보다 우선하므로, 빈 값이면 자동으로 app.env를 사용한다고 기대하면 안 된다. APP_MODE: ""는 빈 문자열이고, APP_MODE:처럼 값이 없는 선언은 외부에서 값을 해결하지 못하면 컨테이너 환경에서 제거될 수 있다.

서비스 env_file을 여러 개 쓰면 위에서 아래로 처리하며 같은 키는 마지막 파일이 덮어쓴다. 예를 들어 common.env 다음에 production.env를 지정했다면 운영값 수정 위치는 production.env일 수 있다. 서비스 env_file의 상대 경로는 Compose 파일 위치를 기준으로 확인하고, CLI --env-file은 명령을 실행하는 현재 디렉터리를 기준으로 확인한다.

빈 값과 미정의 값을 구별해야 한다면 기본값 표현도 살핀다. ${APP_MODE:-development}는 미정의 또는 빈 값에 기본값을 쓰지만, ${APP_MODE-development}는 미정의일 때만 기본값을 쓴다. 필수 입력에는 ${APP_MODE:?APP_MODE is required}를 사용해 값이 없거나 비었을 때 구성 단계에서 오류를 내도록 할 수 있다.

4. .env 수정이 반영되지 않을 때 설정 위치별 점검하기

5. 2026년 기준 env_file 버전 조건과 재생성 확인하기

2026년에도 환경변수 파일 문제를 진단할 때는 설치 버전의 기능 지원 여부가 중요하다. 서비스 env_file의 required: false는 Docker Compose 2.24.0 이상, format: raw는 2.30.0 이상에서 지원한다. 이는 최신 버전 번호가 아니라 각 기능의 최소 지원 버전이다.

required의 기본값은 true이며 false로 설정하면 파일이 없어도 무시한다. 따라서 선택 파일이 누락된 상황에서는 오류 대신 다른 입력원의 값이 남을 수 있다. raw는 env_file 값의 보간을 시도하지 않아 따옴표와 달러 기호를 그대로 전달할 때 유용하다. 지원 조건과 처리 규칙은 Docker 공식 [서비스 env_file 참조 문서](https://docs.docker.com/reference/compose-file/services/#env_file)에 명시돼 있다.

설정 관리 관점에서는 선택 파일과 필수 파일을 구분하는 것이 좋다. 로컬 보조 설정은 누락을 허용할 수 있지만, 운영 필수값까지 조용히 건너뛰면 문제를 늦게 발견할 수 있다. 편의 옵션을 추가하기 전에 누락 시 배포를 중단해야 하는 값인지 판단하는 편이 진단 비용을 줄인다.

최종 구성은 맞는데 컨테이너 값이 이전 값일 때

설정 파일을 저장해도 실행 중인 컨테이너의 환경변수가 즉시 바뀌지는 않는다. docker compose restart는 기존 컨테이너를 재시작하며 변경된 환경변수 설정을 반영하지 않는다. 이 동작은 Docker 공식 [restart 명령 문서](https://docs.docker.com/reference/cli/docker/compose/restart/)에서도 확인할 수 있다.

실제 서비스에서는 최종 구성을 확인한 뒤 다음처럼 대상 서비스를 재생성할 수 있다. 재생성 중에는 서비스 중단이 발생할 수 있으므로 운영 환경의 배포 절차에 맞춰 실행한다. 아래 명령은 계속 실행되는 app 서비스가 있다는 전제이며, 앞의 출력 후 종료하는 최소 예제와는 구분한다.

docker compose config
docker compose up -d --force-recreate app
docker compose exec app printenv APP_MODE

치환 입력값이 다르면 셸 변수와 .env·--env-file을 수정한다.
최종 구성만 다르면 environment, env_file 순서, 추가 Compose 파일을 확인한다.
실행 중인 값만 다르면 같은 프로젝트인지 확인하고 대상 컨테이너를 재생성한다.
컨테이너 값도 맞다면 애플리케이션의 설정 파일·시작 인자·빌드 시점 설정을 확인한다.

.env가 적용되지 않는 문제는 파일 하나의 오류보다 설정 단계 사이의 연결 문제인 경우가 많다. 치환 입력값 → 최종 서비스 구성 → 실행 중인 컨테이너 값 순서로 비교하면 어느 위치를 수정하고 언제 재생성해야 하는지 판단할 수 있다.

5. 2026년 기준 env_file 버전 조건과 재생성 확인하기