> ## Content Index
> Fetch the complete content index at: https://mlog.me/llms.txt
> Use this file to discover other available public pages before exploring further.

# Docker Compose version·external.name 경고 해결법
- URL: https://mlog.me/docker-compose-version-obsolete-external-name-deprecated/
- Published: 2026-08-18T22:12:06.000Z
- Updated: 2026-09-09T12:51:12.000Z
- Description: Docker Compose 실행 시 나타나는 version is obsolete와 external.name deprecated 경고의 원인과 최신 YAML 수정법, 안전한 검증·적용 순서를 정리했습니다.
- Author: mLog
- Tags: 서버·인프라, Docker, Linux, #Docker Compose

> **3줄 요약**
> 
> - `version`은 현재 Docker Compose에서 정보용으로만 남아 있어 삭제해도 됩니다.
> - `external.name`은 `name`과 `external: true`를 같은 단계에 작성하면 됩니다.
> - 이 두 경고는 대개 컨테이너 중단 원인이 아닙니다. 수정 후 `docker compose config -q`로 먼저 검증하세요.

mLog 서버 점검에서는 Nginx 설정 검사 성공과 Compose 형식 경고가 함께 남았습니다. `nginx -t`가 통과했어도 `version`과 `external.name`의 오래된 표현은 별도 정리 대상이었습니다. 아래는 같은 종류의 경고를 보여주는 예시 출력입니다.

```text
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가 설정을 해석할 수 있다면 컨테이너가 정상 실행될 수도 있습니다.

반면 아래 메시지는 별도로 원인을 찾아야 하는 실행 오류입니다.

```text
getaddrinfo ENOTFOUND db
Authentication failed
Connection refused

```

예를 들어 `ENOTFOUND db`는 애플리케이션이 `db`라는 호스트를 찾지 못했다는 뜻일 수 있습니다. 앱과 데이터베이스가 같은 Docker 네트워크에 연결되어 있는지, 서비스 이름이 맞는지를 점검해야 합니다. `version` 경고를 없앤다고 이런 연결 오류까지 해결되지는 않습니다.

## version is obsolete가 나타나는 이유

예전 Compose 파일은 맨 위에서 파일 형식 버전을 선언했습니다.

```yaml
version: "3.8"

```

현재 Docker Compose는 이 값으로 파일 형식을 선택하지 않습니다. 항상 최신 Compose Specification을 기준으로 파일을 검사하므로, 최상위 `version`은 하위 호환을 위한 정보에 가깝고 실제로는 무시됩니다.

따라서 다음 한 줄을 삭제하면 됩니다.

```yaml
version: "3.8"

```

`version`을 삭제해도 Docker Engine이나 컨테이너 이미지가 자동으로 업데이트되지는 않습니다. `image: nginx:alpine` 또는 `image: ghost:6.57.1` 같은 이미지 태그도 그대로 유지됩니다.

자세한 설명은 [Docker 공식 Version and name 문서](https://docs.docker.com/reference/compose-file/version-and-name/?ref=mlog.me)에서 확인할 수 있습니다.

## external.name is deprecated가 나타나는 이유

기존에는 외부 네트워크 이름을 `external` 아래에 넣어 작성하기도 했습니다.

```yaml
networks:
  default:
    external:
      name: npm_common

```

현재 문법에서는 실제 네트워크 이름인 `name`과 외부 네트워크 여부인 `external: true`를 같은 단계에 작성합니다.

```yaml
networks:
  default:
    name: npm_common
    external: true

```

여기서 `npm_common`은 예시입니다. **자신의 서버에 이미 존재하는 네트워크 이름을 그대로 사용해야 합니다.**

`external: true`로 지정한 네트워크는 Compose가 새로 만들거나 관리하지 않습니다. 해당 이름의 네트워크가 없으면 실행 단계에서 찾을 수 없다는 오류가 발생합니다. 현재 문법은 [Docker Compose Networks 공식 문서](https://docs.docker.com/reference/compose-file/networks/?ref=mlog.me)에 설명되어 있습니다.

## 수정 전·후 docker-compose.yml 비교

### 수정 전

```yaml
version: "3.8"

services:
  app:
    image: nginx:alpine
    restart: unless-stopped

networks:
  default:
    external:
      name: npm_common

```

### 수정 후

```yaml
services:
  app:
    image: nginx:alpine
    restart: unless-stopped

networks:
  default:
    name: npm_common
    external: true

```

바뀐 부분은 두 군데뿐입니다.

1. 최상위 `version: "3.8"` 삭제
2. `external.name`을 `name`과 `external: true`로 분리

서비스의 이미지, 볼륨, 포트, 환경변수는 이 경고와 관계가 없으므로 함께 바꿀 필요가 없습니다.

## 추가 실행 결과: 경고는 사라지고 해석된 설정은 같았다

2026년 9월 9일, 본문의 수정 전·후 YAML을 별도 환경에서 **Docker Compose v5.5.0의 `config` 명령으로 실제 검증**했습니다. 운영 서버에 적용한 기록은 아니며, Ubuntu 24.04.3 LTS·Linux 6.18.35·x86\_64에서 공식 릴리스 바이너리의 SHA-256을 배포 체크섬과 대조한 뒤 실행했습니다. Docker 데몬이나 컨테이너는 실행하지 않았습니다.

두 파일은 본문의 예시 그대로 `nginx:alpine`, `restart: unless-stopped`, 외부 네트워크 이름 `npm_common`을 사용했습니다. 바꾼 것은 최상위 `version` 삭제와 `external.name`의 현재 문법 변환뿐입니다. 프로젝트 이름도 같게 고정했습니다. 이미지를 내려받거나 실행하지 않았으므로 이 태그의 이미지 내용이나 Nginx 동작을 검증한 것은 아닙니다.

실험에서는 설치된 Docker CLI를 바꾸지 않고 공식 Compose 바이너리를 독립 실행했습니다. 아래 `./bin/docker-compose`는 구형 Python Compose V1이 아닙니다. 일반 플러그인 설치에서는 기존 `docker compose` 명령으로 같은 옵션을 사용할 수 있습니다.

```bash
./bin/docker-compose -p mlog-compose-validation -f before.yaml config -q
./bin/docker-compose -p mlog-compose-validation -f after.yaml config -q

./bin/docker-compose -p mlog-compose-validation -f before.yaml config --format json
./bin/docker-compose -p mlog-compose-validation -f after.yaml config --format json

```

| 확인 항목               | 수정 전                                          | 수정 후 |
| ------------------- | --------------------------------------------- | ---- |
| config -q 종료 코드     | 0                                             | 0    |
| version 관련 경고       | 발생                                            | 없음   |
| external.name 관련 경고 | 발생                                            | 없음   |
| 해석된 외부 네트워크         | name: npm\_common, external: true             | 동일   |
| 해석된 서비스             | nginx:alpine, unless-stopped, default 네트워크 연결 | 동일   |

수정 전에는 `config -q`의 표준 출력은 비어 있었지만 **표준 오류에 두 경고가 출력**됐습니다. 수정 후에는 표준 출력과 표준 오류가 모두 비어 있었습니다. 즉, 이번에는 양쪽 모두 설정 해석에 성공했으며 수정으로 경고만 사라졌습니다. 종료 코드 0만 보고 경고가 없는 상태라고 판단하면 안 되는 이유입니다.

`config --format json`으로 얻은 전체 모델을 JSON 객체로 읽어 비교했을 때도 같았고, `config --hash app`으로 얻은 서비스 해시도 같았습니다. 이는 **이 예제에서 문법을 정리해도 서비스 설정과 외부 네트워크 이름이 보존됐다**는 확인입니다. 모든 Compose 파일이나 버전에서 무조건 무중단이라는 보장은 아닙니다. `config`의 정규화 역할과 옵션은 [Docker 공식 문서](https://docs.docker.com/reference/cli/docker/compose/config/?ref=mlog.me)에서 확인할 수 있습니다.

이 검증은 `npm_common` 네트워크가 실제 서버에 존재하는지, 컨테이너가 기동되는지, 서비스명이 DNS로 해석되는지까지 확인하지 않았습니다. 운영 적용에서는 본문의 `docker network inspect`, 서비스 상태와 실제 요청 검증을 이어서 수행해야 합니다. **설정 해석 성공과 서비스 동작 성공은 별도의 결과**로 남깁니다.

## 운영 서버에서 안전하게 적용하는 순서

### 1\. 현재 Compose 확인

```bash
docker compose version

```

이 글은 하이픈이 없는 현재 명령인 `docker compose`를 기준으로 합니다. 예전 Python 기반 명령인 `docker-compose`와 혼용하지 않는 편이 좋습니다.

### 2\. Compose 파일 백업

```bash
cp -a docker-compose.yml \
  "docker-compose.yml.bak.$(date +%Y%m%d-%H%M%S)"

```

Compose 파일이나 백업 파일에 비밀번호·API 키가 들어 있다면 공개 저장소에 올리면 안 됩니다. 백업 파일도 원본과 같은 수준으로 보호하세요.

### 3\. 실제 외부 네트워크 이름 확인

```bash
docker network inspect npm_common

```

네트워크 정보가 출력되면 해당 이름이 존재하는 것입니다. 이름을 모른다면 목록을 확인합니다.

```bash
docker network ls

```

하이픈과 밑줄, 대소문자를 포함해 실제 이름을 정확히 사용해야 합니다.

### 4\. YAML 문법 수정

최상단의 `version` 줄을 삭제하고 네트워크 선언을 변경합니다.

```yaml
networks:
  default:
    name: npm_common
    external: true

```

YAML 들여쓰기는 탭 대신 공백을 사용하고 `name`과 `external`이 같은 깊이에 있는지 확인합니다.

### 5\. 실행 전에 설정만 검증

```bash
docker compose config -q

```

문제가 없다면 별도 내용 없이 종료됩니다. 이 명령은 실제 컨테이너를 변경하지 않고 Compose 구성을 검사합니다.

전체 해석 결과가 필요할 때는 다음 명령을 사용할 수 있습니다.

```bash
docker compose config

```

다만 전체 결과에는 `.env`에서 치환된 비밀번호나 토큰이 포함될 수 있습니다. 커뮤니티나 메신저에 그대로 붙여 넣지 말고, 단순 검증에는 `-q`를 사용하는 것이 안전합니다.

관련 옵션은 [docker compose config 공식 문서](https://docs.docker.com/reference/cli/docker/compose/config/?ref=mlog.me)에서 확인할 수 있습니다.

### 6\. 선택 사항: 적용 작업 미리 보기

설치된 Compose가 Dry Run을 지원한다면 예정된 작업을 먼저 확인할 수 있습니다.

```bash
docker compose --dry-run up -d

```

해당 옵션을 지원하지 않는 버전이라면 앞 단계의 `docker compose config -q` 검증을 우선하면 됩니다.

### 7\. 구성 적용과 상태 확인

```bash
docker compose up -d
docker compose ps
docker compose logs --tail=100

```

이 두 문법을 정리하기 위해 먼저 전체 스택을 내릴 필요는 없습니다. `up -d`는 현재 실행 상태와 구성을 비교해 필요한 작업만 수행합니다.

## 절대 습관적으로 실행하면 안 되는 명령

단순한 경고를 없애려고 다음 명령을 실행할 이유는 없습니다.

```bash
# 실행 금지 예시
# docker compose down -v

```

`-v`는 Compose가 관리하는 볼륨을 함께 제거할 수 있습니다. 데이터베이스나 Ghost처럼 데이터를 볼륨에 보관하는 서비스에서는 데이터 손실로 이어질 수 있습니다.

경고 정리는 YAML 수정과 검증의 문제입니다. 볼륨 삭제는 해결 방법이 아닙니다.

## 자주 하는 실수

### 외부 네트워크 이름까지 바꾸기

실제 네트워크가 `npm_common`인데 다음처럼 다른 이름을 쓰면 Compose가 네트워크를 찾지 못합니다.

```yaml
name: another_network

```

기존 이름은 `docker network inspect` 또는 `docker network ls`로 확인한 값을 사용하세요.

### name을 계속 external 아래에 넣기

다음은 경고가 발생하는 기존 형태입니다.

```yaml
external:
  name: npm_common

```

현재 형태에서는 같은 단계에 배치합니다.

```yaml
name: npm_common
external: true

```

### external의 true와 환경변수 문자열 혼동하기

네트워크의 `external`은 불리언 속성이므로 따옴표 없이 작성합니다.

```yaml
external: true

```

반면 `services.*.environment` 아래에 전달하는 값은 애플리케이션이 읽는 문자열일 수 있습니다.

```yaml
environment:
  FEATURE_ENABLED: "true"

```

두 위치는 요구하는 자료형이 다릅니다.

### 외부 네트워크를 무조건 새로 만들기

`network not found`가 나온다면 먼저 이름 오타와 기존 네트워크를 확인하세요.

```bash
docker network ls

```

구조상 정말 새로운 공유 네트워크가 필요한 것이 확실할 때만 생성합니다.

```bash
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 인증, 파일 권한, 포트 충돌 같은 실행 오류는 각각의 로그와 설정을 별도로 점검해야 합니다.

## 마무리

두 경고의 해결 방법은 간단합니다.

```yaml
# 삭제
version: "3.8"

```

```yaml
# 기존 형태
networks:
  default:
    external:
      name: npm_common

```

```yaml
# 현재 형태
networks:
  default:
    name: npm_common
    external: true

```

기존 외부 네트워크 이름을 유지하고 `docker compose config -q`로 검증한 뒤 필요할 때 `docker compose up -d`를 실행하면 됩니다. 무엇보다 Compose 문법 경고와 애플리케이션 장애는 서로 다른 문제라는 점을 구분하는 것이 중요합니다.

## 참고한 공식 문서

- [Version and name top-level elements](https://docs.docker.com/reference/compose-file/version-and-name/?ref=mlog.me)
- [Define and manage networks in Docker Compose](https://docs.docker.com/reference/compose-file/networks/?ref=mlog.me)
- [Networking in Compose](https://docs.docker.com/compose/how-tos/networking/?ref=mlog.me)
- [docker compose config](https://docs.docker.com/reference/cli/docker/compose/config/?ref=mlog.me)