Docker Compose version·external.name 경고 해결법
3줄 요약
version은 현재 Docker Compose에서 정보용으로만 남아 있어 삭제해도 됩니다.external.name은name과external: true를 같은 단계에 작성하면 됩니다.- 이 두 경고는 대개 컨테이너 중단 원인이 아닙니다. 수정 후
docker compose config -q로 먼저 검증하세요.
Docker Compose를 업데이트하거나 오래된 docker-compose.yml을 최신 환경에서 실행하면 다음 경고가 반복될 수 있습니다.
WARN[0000] docker-compose.yml: the attribute `version` is obsolete,
it will be ignored, please remove it to avoid potential confusion
WARN[0000] networks.default: external.name is deprecated.
Please set name and external: true
서비스는 실행되는데 경고가 계속 보여서 무시해도 되는지, 컨테이너를 전부 내려야 하는지 고민하기 쉽습니다. 결론부터 말하면 기존 외부 네트워크 이름은 유지하고 두 부분의 문법만 바꾸면 됩니다.
이 글은 2026년 8월 19일 Docker 공식 문서를 기준으로 확인했습니다.
먼저 확인할 점: 경고와 오류는 다릅니다
위 두 문구는 Compose 파일의 오래된 표현을 알려주는 경고(WARN)입니다. 현재 Compose가 설정을 해석할 수 있다면 컨테이너가 정상 실행될 수도 있습니다.
반면 아래 메시지는 별도로 원인을 찾아야 하는 실행 오류입니다.
getaddrinfo ENOTFOUND db
Authentication failed
Connection refused
예를 들어 ENOTFOUND db는 애플리케이션이 db라는 호스트를 찾지 못했다는 뜻일 수 있습니다. 앱과 데이터베이스가 같은 Docker 네트워크에 연결되어 있는지, 서비스 이름이 맞는지를 점검해야 합니다. version 경고를 없앤다고 이런 연결 오류까지 해결되지는 않습니다.
version is obsolete가 나타나는 이유
예전 Compose 파일은 맨 위에서 파일 형식 버전을 선언했습니다.
version: "3.8"
현재 Docker Compose는 이 값으로 파일 형식을 선택하지 않습니다. 항상 최신 Compose Specification을 기준으로 파일을 검사하므로, 최상위 version은 하위 호환을 위한 정보에 가깝고 실제로는 무시됩니다.
따라서 다음 한 줄을 삭제하면 됩니다.
version: "3.8"
version을 삭제해도 Docker Engine이나 컨테이너 이미지가 자동으로 업데이트되지는 않습니다. image: nginx:alpine 또는 image: ghost:6.57.1 같은 이미지 태그도 그대로 유지됩니다.
자세한 설명은 Docker 공식 Version and name 문서에서 확인할 수 있습니다.
external.name is deprecated가 나타나는 이유
기존에는 외부 네트워크 이름을 external 아래에 넣어 작성하기도 했습니다.
networks:
default:
external:
name: npm_common
현재 문법에서는 실제 네트워크 이름인 name과 외부 네트워크 여부인 external: true를 같은 단계에 작성합니다.
networks:
default:
name: npm_common
external: true
여기서 npm_common은 예시입니다. 자신의 서버에 이미 존재하는 네트워크 이름을 그대로 사용해야 합니다.
external: true로 지정한 네트워크는 Compose가 새로 만들거나 관리하지 않습니다. 해당 이름의 네트워크가 없으면 실행 단계에서 찾을 수 없다는 오류가 발생합니다. 현재 문법은 Docker Compose Networks 공식 문서에 설명되어 있습니다.
수정 전·후 docker-compose.yml 비교
수정 전
version: "3.8"
services:
app:
image: nginx:alpine
restart: unless-stopped
networks:
default:
external:
name: npm_common
수정 후
services:
app:
image: nginx:alpine
restart: unless-stopped
networks:
default:
name: npm_common
external: true
바뀐 부분은 두 군데뿐입니다.
- 최상위
version: "3.8"삭제 external.name을name과external: true로 분리
서비스의 이미지, 볼륨, 포트, 환경변수는 이 경고와 관계가 없으므로 함께 바꿀 필요가 없습니다.
운영 서버에서 안전하게 적용하는 순서
1. 현재 Compose 확인
docker compose version
이 글은 하이픈이 없는 현재 명령인 docker compose를 기준으로 합니다. 예전 Python 기반 명령인 docker-compose와 혼용하지 않는 편이 좋습니다.
2. Compose 파일 백업
cp -a docker-compose.yml \
"docker-compose.yml.bak.$(date +%Y%m%d-%H%M%S)"
Compose 파일이나 백업 파일에 비밀번호·API 키가 들어 있다면 공개 저장소에 올리면 안 됩니다. 백업 파일도 원본과 같은 수준으로 보호하세요.
3. 실제 외부 네트워크 이름 확인
docker network inspect npm_common
네트워크 정보가 출력되면 해당 이름이 존재하는 것입니다. 이름을 모른다면 목록을 확인합니다.
docker network ls
하이픈과 밑줄, 대소문자를 포함해 실제 이름을 정확히 사용해야 합니다.
4. YAML 문법 수정
최상단의 version 줄을 삭제하고 네트워크 선언을 변경합니다.
networks:
default:
name: npm_common
external: true
YAML 들여쓰기는 탭 대신 공백을 사용하고 name과 external이 같은 깊이에 있는지 확인합니다.
5. 실행 전에 설정만 검증
docker compose config -q
문제가 없다면 별도 내용 없이 종료됩니다. 이 명령은 실제 컨테이너를 변경하지 않고 Compose 구성을 검사합니다.
전체 해석 결과가 필요할 때는 다음 명령을 사용할 수 있습니다.
docker compose config
다만 전체 결과에는 .env에서 치환된 비밀번호나 토큰이 포함될 수 있습니다. 커뮤니티나 메신저에 그대로 붙여 넣지 말고, 단순 검증에는 -q를 사용하는 것이 안전합니다.
관련 옵션은 docker compose config 공식 문서에서 확인할 수 있습니다.
6. 선택 사항: 적용 작업 미리 보기
설치된 Compose가 Dry Run을 지원한다면 예정된 작업을 먼저 확인할 수 있습니다.
docker compose --dry-run up -d
해당 옵션을 지원하지 않는 버전이라면 앞 단계의 docker compose config -q 검증을 우선하면 됩니다.
7. 구성 적용과 상태 확인
docker compose up -d
docker compose ps
docker compose logs --tail=100
이 두 문법을 정리하기 위해 먼저 전체 스택을 내릴 필요는 없습니다. up -d는 현재 실행 상태와 구성을 비교해 필요한 작업만 수행합니다.
절대 습관적으로 실행하면 안 되는 명령
단순한 경고를 없애려고 다음 명령을 실행할 이유는 없습니다.
docker compose down -v
-v는 Compose가 관리하는 볼륨을 함께 제거할 수 있습니다. 데이터베이스나 Ghost처럼 데이터를 볼륨에 보관하는 서비스에서는 데이터 손실로 이어질 수 있습니다.
경고 정리는 YAML 수정과 검증의 문제입니다. 볼륨 삭제는 해결 방법이 아닙니다.
자주 하는 실수
외부 네트워크 이름까지 바꾸기
실제 네트워크가 npm_common인데 다음처럼 다른 이름을 쓰면 Compose가 네트워크를 찾지 못합니다.
name: another_network
기존 이름은 docker network inspect 또는 docker network ls로 확인한 값을 사용하세요.
name을 계속 external 아래에 넣기
다음은 경고가 발생하는 기존 형태입니다.
external:
name: npm_common
현재 형태에서는 같은 단계에 배치합니다.
name: npm_common
external: true
external의 true와 환경변수 문자열 혼동하기
네트워크의 external은 불리언 속성이므로 따옴표 없이 작성합니다.
external: true
반면 services.*.environment 아래에 전달하는 값은 애플리케이션이 읽는 문자열일 수 있습니다.
environment:
FEATURE_ENABLED: "true"
두 위치는 요구하는 자료형이 다릅니다.
외부 네트워크를 무조건 새로 만들기
network not found가 나온다면 먼저 이름 오타와 기존 네트워크를 확인하세요.
docker network ls
구조상 정말 새로운 공유 네트워크가 필요한 것이 확실할 때만 생성합니다.
docker network create npm_common
기존 공유 네트워크를 잘못 대체하거나 같은 역할의 네트워크를 중복 생성하지 않도록 주의해야 합니다.
자주 묻는 질문
경고를 무시하고 계속 사용해도 되나요?
현재는 설정이 해석되어 서비스가 실행될 수 있습니다. 하지만 version은 이미 무시되고 external.name은 오래된 표현이므로, 백업과 검증 후 현재 문법으로 정리하는 것이 좋습니다.
version을 삭제하면 Compose 3.8 기능을 사용할 수 없나요?
현재 Compose는 최상위 version 값과 관계없이 Compose Specification으로 파일을 해석합니다. 삭제 자체가 서비스 설정이나 이미지 버전을 바꾸지는 않습니다.
수정 후 서버를 내렸다 올려야 하나요?
이 두 문법만 수정했다면 먼저 docker compose down을 실행할 필요가 없습니다. docker compose config -q로 확인한 뒤, 실행 상태를 구성과 맞출 필요가 있을 때 docker compose up -d를 사용하면 됩니다.
external network not found가 나오면 어떻게 하나요?
docker network inspect 네트워크명과 docker network ls로 실제 이름부터 확인하세요. 새 네트워크가 필요한 구성이 확실할 때만 docker network create 네트워크명을 실행합니다.
경고를 수정했는데 애플리케이션 오류가 계속되는 이유는 무엇인가요?
이 작업은 Compose 문법 경고 두 개만 해결합니다. 데이터베이스 연결, SMTP 인증, 파일 권한, 포트 충돌 같은 실행 오류는 각각의 로그와 설정을 별도로 점검해야 합니다.
마무리
두 경고의 해결 방법은 간단합니다.
# 삭제
version: "3.8"
# 기존 형태
networks:
default:
external:
name: npm_common
# 현재 형태
networks:
default:
name: npm_common
external: true
기존 외부 네트워크 이름을 유지하고 docker compose config -q로 검증한 뒤 필요할 때 docker compose up -d를 실행하면 됩니다. 무엇보다 Compose 문법 경고와 애플리케이션 장애는 서로 다른 문제라는 점을 구분하는 것이 중요합니다.
