Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Docker port가 이미 할당되었을 때: 먼저 확인할 것들

Docker가 port is already allocated라고 말할 때, 실제 문제는 컨테이너 내부보다 host 쪽 충돌인 경우가 많습니다. 다른 container, 다른 Compose stack, 혹은 다른 로컬 프로세스가 이미 그 published port를 쓰고 있는 상태입니다.

짧게 말하면, image나 entrypoint를 바꾸기 전에 먼저 host port를 누가 점유하고 있는지 확인해야 합니다. 여기서 시간을 가장 많이 잃는 경우는 컨테이너를 디버깅하면서 실제 원인은 host에서 놓치는 경우입니다.

먼저 host port 충돌과 app readiness 문제를 구분하세요

겉으로 비슷해 보여도 아래 둘은 다른 상황입니다.

host port가 이미 점유되어 container 자체가 시작되지 않는 경우
container는 시작됐지만 app이 unhealthy 하거나 내부 포트를 잘못 써서 트래픽이 실패하는 경우

첫 번째만 진짜 port allocation 문제입니다. 컨테이너가 이미 떠 있다면 다음 단계는 보통 readiness나 networking 쪽이지, port 충돌이 아닙니다.

충돌이 생기는 흔한 이유

1. 다른 container가 같은 host port를 이미 publish 하고 있음

가장 흔한 경우입니다. 실행 중인 container나 최근 재생성된 service가 여전히 그 port를 잡고 있습니다.

2. 이전 Compose project가 일부만 남아 있음

팀에서는 예전 stack이 내려갔다고 생각하지만 실제로는 일부 service가 계속 살아 있어서 port를 잡고 있는 경우가 많습니다.

3. Docker 밖의 host process가 해당 port를 사용 중임

로컬 database, web server, tunneling tool, IDE extension, 개발용 daemon이 충돌 원인일 수 있습니다.

4. host port와 container port를 혼동하고 있음

예를 들어 앱은 컨테이너 내부에서 8080으로 뜨지만 publish는 18080:8080으로 했는데, 팀이 8080만 이야기하며 서로 다른 포트를 보고 있을 수 있습니다.

5. 여러 환경이 같은 기본 포트를 재사용하고 있음

로컬 개발에서 branch별 stack, 테스트용 stack, 현재 Compose project가 모두 5432, 6379, 8080을 쓰려고 해서 자주 충돌합니다.

실전 점검 순서

1. 실행 중인 container와 published port를 확인하세요

아래 명령으로 시작하면 됩니다.

docker ps
docker port <container>
netstat -ano | findstr :8080

이렇게 보면 Docker가 이미 host port를 점유한 건지, 아니면 다른 host process가 먼저 bind 한 건지 빠르게 알 수 있습니다.

2. 이전 Compose stack이 남아 있는지 확인하세요

Compose를 쓴다면 어떤 project와 service가 아직 살아 있는지 봐야 합니다. 절반만 내려간 stack 하나가 계속 충돌을 만들 수 있습니다.

여러 branch를 동시에 띄우거나 project name을 재사용할 때 특히 흔합니다.

3. 의도한 port mapping을 다시 확인하세요

아래 셋을 분리해서 생각해야 합니다.

애플리케이션이 container 내부에서 listen 하는 port
Docker가 host에 publish 하는 port
다른 서비스나 팀원이 실제로 접근하려는 port

이 셋 중 다른 것을 보고 있으면 디버깅이 계속 엇갈립니다.

4. port를 비울지, mapping을 바꿀지 결정하세요

기존 점유자가 stale 하거나 잘못된 것이면 종료하고, 정상적으로 필요한 서비스라면 새 컨테이너 쪽 host port를 바꾸는 것이 맞습니다.

다만 원인을 모른 채 port만 바꾸면 환경 관리 문제를 가린 채 넘어가게 됩니다.

5. 충돌이 해결됐는데도 트래픽이 실패하면 다른 가이드로 넘어가세요

이제는 port allocation 문제가 아닐 가능성이 큽니다. app log, health check, bind address, reverse proxy 설정을 보는 쪽이 맞습니다.

그럴 때는 Docker container keeps restarting를 같이 보세요.

패턴을 찾은 뒤 어떻게 바꿀지

다른 container가 port를 점유한 경우

stale container를 중지하거나 제거하고, 필요한 경우 한쪽 service의 host port를 변경하세요.

Compose stack끼리 충돌하는 경우

project naming을 더 명확히 하고, 오래된 stack을 의도적으로 정리하고, docker compose up이 항상 이전 서비스를 대체해준다고 가정하지 않는 편이 좋습니다.

host process가 점유한 경우

그 프로세스를 중지하거나 로컬 개발용 기본 포트와 겹치지 않는 번호를 선택하세요.

문서나 설정에서 mapping이 잘못된 경우

Compose 파일, 실행 명령, 팀 문서를 고쳐서 사람들이 더 이상 잘못된 host/container port를 보지 않도록 해야 합니다.

빠른 체크리스트

Docker가 port is already allocated라고 할 때는 이 순서가 가장 빠릅니다.

실행 중인 container를 본다
대상 port의 host listener를 확인한다
남아 있는 Compose service가 있는지 본다
host port와 container port mapping을 다시 확인한다
점유자를 알게 된 뒤에만 종료하거나 remap 한다

FAQ

Q. host port만 바꾸면 끝인가요?

그럴 때도 있지만, 원래 포트를 누가 왜 쓰고 있었는지 이해하는 편이 더 안전합니다.

Q. 가장 빠른 첫 단계는 무엇인가요?

image나 app 설정을 건드리기 전에 실행 중인 container와 host listener를 먼저 보는 것입니다.

Q. Compose에서 더 자주 생기는 이유가 있나요?

서비스 수가 많고, project lifecycle이 겹치기 쉬워서 stale ownership을 놓치기 쉽기 때문입니다.

Q. container는 이제 뜨는데 app이 여전히 안 보입니다. 다음은 뭘 봐야 하나요?

그때는 port allocation보다 bind address, health, log, startup behavior를 봐야 합니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.