Docker: Bind failed — port is already allocated

안녕하세요, BlueByte입니다. docker run -p 8080:80 ...(또는 docker compose up)을 실행했는데 컨테이너 대신 port is already allocated로 끝나는 빨간 줄이 뜹니다. 깨진 건 아무것도 없습니다 — Docker가 커널에 컨테이너용 호스트 포트 8080을 잡아 달라고 요청했는데 이미 무언가가 그 포트를 쥐고 있는 것뿐입니다. 오늘은 메시지 변형, 포트가 왜 이미 잡혀 있는지, 정확히 무엇이 쥐고 있는지 찾는 법, 포트를 비우거나 컨테이너를 옮기는 법, 그리고 재발을 막는 법까지 하나씩 짚어보겠습니다.

port is already allocated가 실제로 뜻하는 것

-p HOST_PORT:CONTAINER_PORT로 포트를 게시하면 Docker는 트래픽이 컨테이너에 닿도록 그 호스트 포트를 예약합니다. 호스트 포트가 사용 중이면 컨테이너가 시작되기도 전에 실행이 실패합니다. 최신 Docker(29.6에서 확인)는 누가 포트를 쥐고 있느냐에 따라 데몬이 두 가지 형태 중 하나를 출력합니다. 다른 컨테이너가 이미 그 포트를 게시 중이면:

docker: Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint web (...):
Bind for 0.0.0.0:8080 failed: port is already allocated

Docker가 아닌 호스트 프로세스가 쥐고 있으면:

docker: Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint web (...):
failed to bind host port 0.0.0.0:8080/tcp: address already in use

userland proxy를 쓰던 옛 Docker는 두 번째를 Error starting userland proxy: listen tcp4 0.0.0.0:8080: bind: address already in use로 표현했습니다. 어느 쪽이든 뜻은 같습니다 — 호스트 포트가 비어 있지 않다는 것입니다.

호스트 포트가 이미 잡혀 있는 이유

bind는 몇 가지 구체적 이유 중 하나로 실패합니다:

• 실행 중인 다른 컨테이너가 이미 그 호스트 포트를 게시 중.
• --restart 정책이 붙은 정지됐지만 제거되지 않은 컨테이너가 되살아나 포트를 다시 잡음, 또는 크래시한 실행이 매핑을 남김.
• 로컬 Postgres, 다른 개발 서버, 잊고 있던 node나 python 같은 평범한 호스트 프로세스가 리스닝 중.
• 하나의 compose.yaml에서 같은 호스트 포트를 두 번 게시(두 서비스가 모두 8080: 매핑).
• 스크립트 안 두 개의 docker run이 모두 8080을 요청.

무엇이 포트를 쥐고 있는지 정확히 찾기

추측하지 말고 물어보세요. 먼저 컨테이너가 쥐고 있는지 확인합니다:

docker ps --filter publish=8080 --format '{{.Names}}\t{{.Ports}}'

api   5432/tcp, 0.0.0.0:8080->80/tcp

컨테이너 이름이 나오면 그게 범인입니다. 한 컨테이너의 매핑을 읽으려면:

docker port api
# 80/tcp -> 0.0.0.0:8080

일치하는 컨테이너가 없으면 호스트 프로세스입니다. Linux/macOS에서는 ss(또는 lsof)가 소유자와 PID를 알려줍니다:

ss -ltnp | grep :8080
# LISTEN 0 128 127.0.0.1:8080 0.0.0.0:* users:(("python3",pid=693238,fd=3))

Windows에서는 netstat가 같은 일을 합니다:

netstat -ano | findstr :8080

마지막 열이 PID이고, 그게 처리해야 할 대상입니다.

macOS에서는 lsof가 같은 답을 더 빨리 줍니다:

lsof -nP -iTCP:8080 -sTCP:LISTEN

어느 도구를 쓰든 목표는 같습니다: 무언가를 건드리기 전에 "무언가가 쥐고 있다"를 이름과 PID로 바꾸는 것입니다.

포트를 비우거나 컨테이너를 옮기기

찾은 것에 맞는 해결을 고르세요:

컨테이너가 쥐고 있음 — 정지 후 제거하거나 스택 전체를 내립니다:

docker stop api && docker rm api
# 또는 Compose 프로젝트 전체:
docker compose down

호스트 프로세스가 쥐고 있음 — 그 프로세스나 서비스를 멈춥니다. ss/netstat에서 얻은 PID로:

kill 693238            # Linux/macOS
taskkill /PID 693238 /F   # Windows

8080을 두고 다툴 필요가 없을 때 — 다른 호스트 포트로 게시하거나(컨테이너 포트는 그대로), 한 인터페이스에만 바인딩하거나, -P로 Docker가 빈 포트를 고르게 하세요:

docker run -p 8081:80 nginx              # 다른 호스트 포트
docker run -p 127.0.0.1:8080:80 nginx    # loopback 전용
docker run -P nginx                       # 무작위 호스트 포트; docker port로 확인

Windows에서는 아무도 리스닝하지 않아도 예약된 범위가 bind를 막습니다

Windows에는 찾을 프로세스가 없는 원인이 있습니다. NAT 서비스(winnat)와 동적 포트 범위가 포트 블록 전체를 예약할 수 있어, netstat에 그 포트에 아무것도 없어도 Docker의 bind가 거부됩니다. 메시지는 보통 Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:8080 -> ...: bind: An attempt was made to access a socket in a way forbidden by its access permissions로 뜹니다 — "이미 사용 중"이 아니라 Winsock 오류 10013입니다. 유령 프로세스를 쫓기 전에 예약된 범위를 먼저 나열하세요:

netsh interface ipv4 show excludedportrange protocol=tcp

호스트 포트가 나열된 범위 안에 있으면 그게 원인의 전부입니다. 모든 범위 밖의 포트를 고르거나, NAT 서비스를 껐다 켜 예약을 풀어 주세요(Docker Desktop 재시작도 같은 리셋을 합니다):

net stop winnat
net start winnat

아무것도 포트를 "쓰고" 있지 않은데 bind가 실패하는 유일한 경우입니다 — Windows에서 docker ps와 netstat가 모두 비어 있으면 excluded 범위부터 확인하세요.

실제 사례: 크래시한 컨테이너가 아직 8080을 쥐고 있음

docker compose up을 했는데 부팅 중 죽었고, 설정을 고쳐 다시 실행했더니 Bind for 0.0.0.0:8080 failed: port is already allocated가 뜹니다. docker ps에는 아무것도 없어 호스트 프로세스처럼 보입니다. 그런데 docker ps -a를 보면 이전 컨테이너가 restart: unless-stopped로 Exited 상태였고, 두 명령 사이에 되살아나 포트를 다시 잡은 것입니다. docker compose down(또 한 번의 up이 아니라)이 그 컨테이너를 제거하고 8080을 풀어 주며, 다음 up은 깨끗하게 bind됩니다. 교훈: docker ps에 보이지 않는 매핑도 docker ps -a에서는 여전히 컨테이너일 수 있습니다.

컨테이너가 실제로 포트를 잡았는지 확인

고친 뒤 매핑이 존재하고 응답하는지 봅니다:

docker ps --filter publish=8080
# api ... 0.0.0.0:8080->80/tcp   Up 6 seconds
curl -sSf http://localhost:8080/ >/dev/null && echo ok

docker ps에 0.0.0.0:8080-> 행이 보이고 curl이 2xx/3xx를 받으면 포트가 bind됐고 트래픽이 컨테이너에 닿는 것입니다.

충돌이 다시 일어나지 않게 하기

스택마다 고유한 호스트 포트를 주고 적어 두세요 — compose.yaml이 단일 진실 소스라, 그 안의 중복된 8080:은 리뷰에서 바로 잡힙니다. 다른 머신에서 접근할 필요가 없는 것은 127.0.0.1:에 바인딩해 0.0.0.0의 두 프로젝트가 같은 포트를 두고 다투지 않게 하세요. 스택을 내릴 때는 Ctrl-C 대신 docker compose down을 써서 restart 정책 컨테이너가 남아 포트를 되찾지 않게 합니다.

address already in use·EADDRINUSE와 어떻게 다른가

port is already allocated는 Docker 자체 메시지입니다: 장부가 이미 그 호스트 포트를 어떤 컨테이너용으로 예약했다는 뜻입니다. address already in use(및 옛 userland-proxy 줄)는 Docker가 아닌 소켓이 포트를 쥐고 있어 커널이 bind를 거부하는 것입니다 — 소유자만 다른 같은 충돌이며, 그래서 하나는 docker ps로, 다른 하나는 ss로 안내합니다. Node의 맨 EADDRINUSE나 평범한 서버의 bind: address already in use는 Docker가 경로에 없는 같은 커널 오류로, 이때는 호스트 프로세스를 직접 쫓습니다. 셋 다 한 가지를 말합니다: 두 대상이 하나의 포트를 원한다는 것.