Docker "container name is already in use" 에러 5분 해결법

방금 전까지 잘 돌던 컨테이너를 다시 띄웠을 뿐인데 갑자기 이런 에러를 만나셨죠?

docker: Error response from daemon: Conflict. The container name "/myapp" is already in use by container "a1b2c3d4...". You have to remove (or rename) that container to be able to reuse that name.

먼저 안심하세요. 이건 장애가 아닙니다. 데이터가 날아간 것도, Docker가 고장 난 것도 아니고 30초면 끝나는 아주 흔한 상황입니다. 같은 이름의 컨테이너가 디스크에 남아 있어서 이름이 겹쳤을 뿐이에요. 급하면 아래 "즉시 해결" 블록부터 복붙하고, 시간 되면 원인과 예방법까지 읽어보세요.

참고: 이 글은 로컬/단일 호스트 Docker 환경 한정입니다. Kubernetes의 ImagePullBackOff·CrashLoopBackOff 같은 파드 라이프사이클 이슈는 원인과 해결이 전혀 다르니 K8s 환경이라면 다른 글을 참고하세요.

급하면 여기부터: docker run 환경 30초 해결

원인은 한 줄로 정리됩니다. 컨테이너는 종료(Exited)돼도 삭제 전까지 이름을 계속 점유합니다. 그래서 같은 이름으로 다시 docker run 하면 충돌이 나죠.

1단계 — 범인 확인 (30초 진단)

docker ps -a | grep myapp

이렇게 종료된 컨테이너가 이름을 붙들고 있는 게 보일 겁니다.

a1b2c3d4e5f6   nginx   "/docker-ent..."   10분 전   Exited (0) 5분 전   myapp

STATUS가 Exited (0)인데도 NAMES 칸에 myapp이 그대로 남아 있죠. 바로 이놈이 이름을 점유 중인 범인입니다.

여기서 docker ps와 docker ps -a의 차이를 꼭 알아두세요.

docker ps로 안 보인다고 "없는 줄" 알았다가 충돌이 나는 게 가장 흔한 함정입니다. 이름 점유 여부는 반드시 -a로 확인하세요.

2단계 — 상태별 복붙 명령 3종

# (1) 종료된 컨테이너 삭제 — 가장 안전, 평소엔 이것
docker rm myapp

# (2) 실행 중이어도 강제 삭제 — ⚠️ 돌고 있는 컨테이너를 즉시 죽이고 삭제. 급할 때만
docker rm -f myapp

# (3) 정상 종료 후 삭제 — 우아하게 멈추고 지우고 싶을 때
docker stop myapp && docker rm myapp

삭제 후 원래 명령을 다시 실행하면 끝입니다.

docker run -d --name myapp nginx

docker compose 환경에서 같은 에러가 났을 때

Compose에서도 container_name을 고정하면 똑같은 충돌이 납니다.

# docker-compose.yml
services:
  web:
    image: nginx
    container_name: myapp   # ← 이름을 못 박아서 재기동 시 충돌 가능
    ports:
      - "8080:80"

container_name을 명시하면 Compose가 자동으로 붙이는 프로젝트 접두사(프로젝트명-서비스명-번호)가 사라지고 이름이 고정됩니다. 이 상태에서 이전 컨테이너가 남아 있으면 up 할 때 충돌이 나죠. 해결 흐름은 이렇습니다.

# 방법 A) 기존 컨테이너를 강제로 다시 만들며 기동
docker compose up -d --force-recreate

# 특정 서비스만 재생성하고 싶다면
docker compose up -d --force-recreate web

# 방법 B) 깔끔하게 내렸다가 다시 올리기 (가장 확실)
docker compose down && docker compose up -d

참고로 요즘은 하이픈 붙은 docker-compose(V1)가 아니라 띄어쓰기 docker compose(V2) 가 표준입니다. 명령어가 헷갈린다면 V2 쪽으로 통일하세요.

실무 경험 한마디: CI/CD 파이프라인에서 고정 container_name을 쓰면 재배포 때마다 이 충돌이 단골로 터집니다. 저는 배포 스크립트 맨 앞에 docker compose down --remove-orphans를 한 줄 넣어 두거나, 아예 container_name을 빼고 Compose가 자동 생성하는 이름을 쓰도록 바꿔서 재배포 충돌을 없앴습니다. 이름 고정이 꼭 필요한 게 아니라면 빼는 쪽이 운영이 훨씬 편합니다.

다시는 안 만나기: 근본 예방법

문제를 매번 지우는 것보다 안 생기게 하는 게 낫죠.

• 일회성 컨테이너엔 --rm: 종료되는 순간 자동 삭제돼 이름이 남지 않습니다.
  Bash복사

  docker run --rm --name test nginx

• 장기 실행 서비스엔 재시작 정책: 죽거나 데몬이 재시작돼도 알아서 살아납니다.
  Bash복사

  docker run -d --restart unless-stopped --name myapp nginx

• 네이밍 규칙으로 충돌 원천 차단: 환경별로 접두사/접미사를 붙이면 이름이 겹칠 일이 없습니다.
  CODE복사

  app-dev    # 개발
  app-stage  # 스테이징
  app-prod   # 운영

결론: 상황별 치트시트

행동 가이드는 간단합니다. 급하면 docker rm -f, 평소엔 --rm. 이 두 개만 기억하면 이 에러로 다시 시간을 뺏기지 않습니다.

자주 묻는 질문 (FAQ)

Q. 컨테이너를 지우긴 싫고 이름만 바꾸고 싶어요. A. docker rename을 쓰면 됩니다. 데이터나 설정은 그대로 두고 이름만 변경돼서, 충돌나는 이름을 비워줄 수 있습니다.

docker rename myapp myapp-old

Q. 왜 같은 이름의 컨테이너를 여러 개 못 만드나요? A. Docker에서 컨테이너 이름은 ID와 함께 고유 식별자 역할을 합니다. docker stop myapp처럼 이름으로 컨테이너를 지목하려면 그 이름이 유일해야 하므로 중복이 허용되지 않습니다. 여러 개가 필요하면 --name 옵션을 빼서 Docker가 임의 이름을 붙이게 하세요.

Q. docker rm이 "container is running" 이라며 거부해요. A. 실행 중인 컨테이너는 그냥 rm으로 못 지웁니다. docker stop <name> 후 docker rm <name> 하거나, 급하면 docker rm -f <name>로 강제 삭제하세요.