오늘의 삽질 docker compose up할때 --build를 잘 챙겨주자...

[Docker] docker compose up vs --build 옵션 차이점 완벽 정리: 왜 내 코드는 반영이 안 될까?

Docker Compose를 사용하다 보면 가장 흔하게 겪는 상황이 있습니다. 분명 코드를 수정하고 컨테이너를 다시 실행했는데, 수정 사항이 전혀 반영되지 않는 경우입니다.

이때 범인은 바로 명령어 옵션의 차이에 있습니다. 오늘은 docker compose up -d와 --build 옵션의 결정적인 차이를 정리해 봅니다.

1. docker compose up -d (기존 이미지 재사용)

가장 일반적으로 사용하는 명령어입니다.

docker compose up -d

• 동작 방식:
  1. Docker는 현재 프로젝트의 이미지가 로컬에 존재하는지 확인합니다.
  2. 이미지가 이미 있다면, 새로 빌드하지 않고 기존 이미지를 그대로 사용하여 컨테이너를 실행합니다.
  3. 이미지가 없을 때만 Dockerfile을 읽어 빌드를 수행합니다.
• 언제 사용하나요?
  • 단순히 컨테이너를 껐다 켤 때.
  • 서버 재부팅 후 서비스를 다시 올릴 때.
  • 코드 변경 사항이 없을 때.

주의: 소스 코드를 수정했더라도 이 명령어로 실행하면, Docker는 "이미지 있네? 그냥 이거 써야지" 하고 수정 전의 옛날 코드가 담긴 이미지를 실행해 버립니다.

2. docker compose up -d --build (강제 재빌드)

코드 수정 사항을 반영하고 싶다면 반드시 이 옵션을 붙여야 합니다.

docker compose up -d --build

• 동작 방식:
  1. 기존 이미지가 있든 없든 상관없이, 무조건 이미지를 새로 빌드합니다.
  2. 이 과정에서 변경된 소스 코드(COPY . .)나 Dockerfile의 변경 사항이 새 이미지에 반영됩니다.
  3. 빌드가 완료되면 새 이미지를 기반으로 컨테이너를 (재)실행합니다.
• 언제 사용하나요?
  • 소스 코드를 수정했을 때 (가장 중요!)
  • package.json, requirements.txt 등 의존성 파일을 변경했을 때.
  • Dockerfile 자체를 수정했을 때.

3. 한눈에 보는 요약

특징	docker compose up -d	docker compose up -d --build
이미지 빌드	이미지가 없으면 빌드, 있으면 스킵	무조건 새로 빌드
코드 변경 반영	반영 안 됨 (기존 이미지 사용)	반영 됨 (새 이미지 생성)
주 사용 목적	서비스 재시작, 배포된 상태 유지	개발 중 코드 수정 반영, 설정 변경
속도	빠름 (빌드 과정 생략)	상대적으로 느림 (빌드 시간 소요)

💡 결론

• "어? 왜 코드를 고쳤는데 똑같지?" 싶을 때는 십중팔구 --build를 빼먹은 것입니다.
• 개발 중에는 습관적으로 docker compose up -d --build를 사용하는 것이 정신건강에 좋습니다.

---

태그: #Docker #DockerCompose #DevOps #개발팁 #도커트러블슈팅