코드 한 줄만 고쳤는데 npm install이나 pip install 단계가 매번 처음부터 도는 경우가 있습니다. 반대로 apt-get update가 오래된 결과로 캐시돼 새 패키지가 설치되지 않기도 합니다. 둘 다 원인은 같습니다. 빌드 캐시는 Dockerfile 명령어를 위에서 아래로 비교하고, 한 단계라도 달라지면 그 아래를 전부 다시 실행하기 때문입니다.
로그에서 캐시가 끊긴 첫 단계를 찾고, 그 단계의 입력이 왜 바뀌었는지 보는 순서로 풀어 갑니다.
빌드 캐시 문제 증상과 원인 진단
Docker 이미지 빌드 시 캐시 문제가 발생하면 주로 다음과 같은 증상을 보입니다.
- 빌드 시간 증가: 빌드 로그에서
CACHED표시 없이 다시 실행되는 단계가 많고, 바꾼 적 없는 의존성 설치 단계까지 매번 처음부터 실행됩니다. - 최신 변경 사항 미반영:
apt-get update나npm install과 같은 명령어가 캐시되어 최신 패키지나 의존성이 설치되지 않는 경우가 있습니다. 또는ADD나COPY명령어로 추가한 파일이 업데이트되지 않는 것처럼 보일 수 있습니다.
이러한 증상을 진단하려면 빌드 로그에서 캐시가 끊긴 첫 단계를 찾아야 합니다. Docker Engine 23.0부터 Linux의 기본 빌더는 BuildKit이고, BuildKit은 캐시를 재사용한 단계에 CACHED 를 붙입니다. 단계별 로그를 한 줄씩 보려면 --progress=plain 을 붙여 빌드합니다.
docker build --progress=plain -t my-image .
출력에서 CACHED 가 붙은 단계는 캐시를 재사용한 것이고, 붙지 않은 단계는 새로 실행된 것입니다. 위에서부터 읽어 내려가 CACHED 가 처음 사라지는 단계가 캐시가 무효화된 지점이며, 그 아래 단계는 모두 다시 실행됩니다. 대개 그 지점의 COPY 대상 파일이 바뀌었거나 명령어 문자열이 바뀐 경우입니다.
예전 빌더(DOCKER_BUILDKIT=0)를 쓰는 환경이라면 Using cache 가 캐시 재사용, Running in <container_id> 가 새 실행을 뜻합니다.
Docker 빌드 캐시의 작동 원리 및 무효화 조건
Docker는 Dockerfile의 각 명령어를 개별적인 빌드 단계로 간주하고, 각 단계는 이미지의 새로운 레이어를 생성합니다. 이미지 빌드 시 Docker는 각 명령어에 대해 빌드 캐시에서 재사용 가능한 레이어가 있는지 확인합니다. 캐시 재사용은 이전 빌드에서 동일한 명령어가 실행되었고 해당 레이어가 변경되지 않았을 때 발생하며, 이는 빌드 속도를 크게 높입니다.
캐시 무효화는 다음과 같은 조건에서 발생합니다.
- Dockerfile 명령어 변경: Dockerfile 내의 명령어 문자열 자체가 변경되면 해당 단계의 캐시가 무효화됩니다. 예를 들어,
RUN apt-get update가RUN apt-get update -y로 바뀌면 캐시가 무효화됩니다. ADD또는COPY명령어의 파일 변경: 빌더는 복사 대상 파일의 메타데이터로 캐시 체크섬을 계산하고, 관련 파일 중 하나라도 바뀌면 해당 명령어의 캐시를 무효화합니다.note[BuildKit 내부 캐시와 `--cache-from`의 차이점] `--cache-from`/`--cache-to` 는 레이어 캐시(각 단계를 다시 실행할지 판단하는 캐시)를 빌드 환경 밖으로 내보내고 가져오는 기능입니다. 캐시 마운트(`--mount=type=cache`)는 단계가 다시 실행될 때 그 안에서 쓰는 디렉터리(패키지 다운로드 캐시 등)를 빌더에 남겨 두는 기능이며, 레지스트리 캐시로 내보내지지 않습니다. :::⚠️ 수정 시간(mtime)과 캐시 무효화ADD및COPY명령어의 경우, 파일의 수정 시간(mtime)은 캐시 체크섬 계산에 고려되지 않습니다. 즉,git checkout등으로 파일의mtime만 바뀌고 내용이 그대로라면 캐시는 무효화되지 않습니다. 반대로 파일 내용이 바뀌면 캐시가 무효화됩니다. :::- 하위 레이어의 캐시 무효화: 한 레이어의 캐시가 무효화되면, 해당 레이어 이후의 모든 Dockerfile 명령어는 새로운 이미지를 생성하며 캐시를 사용하지 않습니다. 이는 캐시 무효화가 연쇄적으로 발생하여 빌드 시간을 길어지게 하는 주요 원인입니다.
RUN명령어의 특성:RUN명령어는 명령어 문자열 자체를 사용하여 캐시 일치 여부를 찾습니다. 컨테이너 내부에서 업데이트된 파일은 캐시 일치 여부 결정에 영향을 주지 않습니다. 예를 들어,RUN apt-get update명령어가 캐시되면, 실제 패키지 목록이 업데이트되었더라도 Docker는 캐시된 레이어를 재사용할 수 있습니다. 최신 패키지를 강제로 가져오려면RUN apt-get update && apt-get install -y <package>를 같은 레이어에 두거나,docker build --no-cache를 사용해야 합니다.
BuildKit 활용으로 빌드 캐시 최적화
BuildKit은 Docker의 빌드 엔진으로, 예전 빌더에 없던 캐시 마운트, 외부 캐시 내보내기 같은 기능을 제공합니다. Docker Desktop과 Docker Engine 23.0 이상에서는 BuildKit이 기본 빌더이므로 따로 켤 필요가 없습니다.
BuildKit 사용 여부 확인
빌드 로그가
#1 [internal] load build definition from Dockerfile처럼#번호형식으로 나오면 BuildKit이 동작 중입니다. 오래된 Engine에서Step 1/5형식이 나온다면 Engine을 업그레이드하는 것이 좋고, 당장 어렵다면 빌드할 때만DOCKER_BUILDKIT=1환경 변수를 지정할 수 있습니다.BASHDOCKER_BUILDKIT=1 docker build -t my-image .캐시 마운트 (
RUN --mount=type=cache)BuildKit의 캐시 마운트는 빌드 간에 지속적인 캐시 위치를 지정하여 의존성 설치 시간을 크게 단축할 수 있는 강력한 기능입니다. 이 캐시는 이미지 레이어에 포함되지 않고 BuildKit에 의해 관리되는 별도의 영구 캐시 볼륨처럼 작동합니다.
예를 들어 Node.js 프로젝트에서는 npm의 다운로드 캐시 디렉터리(
/root/.npm)를 캐시 마운트로 지정해,package.json이 바뀌어 설치 단계가 다시 실행되더라도 이미 받은 패키지는 다시 내려받지 않게 할 수 있습니다.node_modules자체를 캐시하는 것이 아닙니다.DOCKERFILE# Dockerfile 예시 FROM node:24-alpine WORKDIR /app COPY package*.json ./ # npm 다운로드 캐시를 빌드 간에 재사용 RUN --mount=type=cache,target=/root/.npm \ npm ci COPY . . CMD ["npm", "start"]이 예시에서
/root/.npm은 빌드 간에 유지되어npm ci가 패키지를 다시 다운로드하지 않습니다. 캐시 마운트의 내용은 최종 이미지에 들어가지 않습니다.외부 캐시 소스 활용 (
--cache-from,--cache-to)CI 러너처럼 매번 빈 환경에서 빌드하면 로컬 캐시가 없습니다. 이때
docker buildx build의--cache-to로 빌드 캐시를 레지스트리에 내보내고, 다음 빌드에서--cache-from으로 가져와 재사용할 수 있습니다.BASHdocker buildx build --push -t <registry>/app:latest \ --cache-to type=registry,ref=<registry>/app:buildcache,mode=max \ --cache-from type=registry,ref=<registry>/app:buildcache .mode=max는 최종 이미지에 들어가지 않는 중간 단계(멀티 스테이지의 빌드 스테이지 등)의 캐시까지 내보냅니다. 기본docker드라이버는 containerd 이미지 저장소를 켠 경우에만 레지스트리 캐시를 지원하므로, 그렇지 않다면docker buildx create --driver docker-container --use로 별도 빌더를 만들어 사용해야 합니다.
Dockerfile 최적화 전략
캐시 효율성을 극대화하기 위한 Dockerfile 작성 모범 사례는 다음과 같습니다.
명령어 순서 최적화
Dockerfile에서 자주 변경되지 않는 명령어를 상단에 배치하고 자주 변경되는 명령어를 하단에 배치하여 캐시 재사용률을 높일 수 있습니다. 캐시 무효화는 해당 레이어부터 아래로 전파되기 때문입니다.
나쁜 예입니다.
DOCKERFILEFROM python:3.13-slim WORKDIR /app # 코드가 바뀔 때마다 이 단계부터 아래 단계가 모두 다시 실행된다 COPY . . RUN pip install -r requirements.txt CMD ["python", "app.py"]좋은 예입니다.
DOCKERFILEFROM python:3.13-slim WORKDIR /app # 의존성 파일만 먼저 복사: requirements.txt 가 바뀔 때만 아래 설치 단계가 다시 실행된다 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 코드 변경은 여기부터만 영향을 준다 COPY . . CMD ["python", "app.py"]Dockerfile에서
#주석은 줄 맨 앞에서만 인식됩니다.COPY . . # 설명처럼 명령어 뒤에 붙이면#과 뒤 단어가 복사할 파일 이름으로 해석되어 빌드가 실패하므로, 주석은 항상 별도 줄에 씁니다..dockerignore파일 활용.dockerignore파일을 사용하여 빌드 컨텍스트에 불필요한 파일(예:.git,node_modules,logs,.env)을 포함하지 않음으로써ADD나COPY명령어의 캐시 무효화를 줄이고 빌드 속도를 향상시킬 수 있습니다. 불필요한 파일이 변경되어도 캐시가 무효화되지 않게 됩니다.CODE# .dockerignore 예시 .git .vscode/ node_modules/ npm-debug.log Dockerfile .dockerignore멀티 스테이지 빌드
멀티 스테이지 빌드는 최종 이미지 크기를 줄일 뿐만 아니라, 각 스테이지에서 필요한 의존성만 빌드하여 캐시 효율성을 높이는 데 도움이 됩니다. 예를 들어, 빌드 도구와 런타임 환경을 분리할 수 있습니다.
DOCKERFILE# 멀티 스테이지 빌드 예시 # Stage 1: 빌드 스테이지 FROM node:24-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # Stage 2: 런타임 스테이지 (운영 의존성만 설치) FROM node:24-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY --from=builder /app/build ./build CMD ["npm", "start"]
불필요한 캐시 정리 및 관리
때로는 캐시가 너무 오래되었거나 예상치 못한 문제를 일으킬 때 수동으로 캐시를 정리해야 합니다.
--no-cache플래그 사용docker build명령어에--no-cache플래그를 사용하면 모든 빌드 캐시를 비활성화하고 모든 레이어를 처음부터 다시 빌드합니다. 이는 캐시로 인해 발생하는 문제를 완전히 회피하고 싶을 때 유용합니다.BASHdocker build --no-cache -t my-image .베이스 이미지까지 최신 버전으로 다시 가져오려면
--pull플래그를 함께 사용할 수 있습니다.BASHdocker build --no-cache --pull -t my-image .docker builder prune명령어를 이용한 BuildKit 캐시 정리docker builder prune명령어를 사용하여 BuildKit 캐시를 수동으로 정리할 수 있습니다. 이는 디스크 공간을 확보하는 데 도움이 됩니다.오래된 캐시 제거:
--filter "until=168h"옵션으로 168시간(7일)보다 오래된 캐시를 제거할 수 있습니다.BASHdocker builder prune --filter "until=168h"일정 용량만 남기고 정리:
--reserved-space를 주면 캐시를 지정한 크기만큼은 남기고, 그보다 많으면 오래 쓰지 않은 캐시부터 지웁니다. 명령을 실행할 때 한 번 정리하는 것이며 상시 제한이 걸리는 것은 아닙니다. 이 옵션은 최신 Docker CLI 기준이고, 이전 버전에서는 같은 역할의--keep-storage를 씁니다.BASHdocker builder prune --reserved-space 5GB사용하지 않는 캐시 전부 정리:
-a(--all)를 붙이면 dangling 캐시뿐 아니라 사용하지 않는 빌드 캐시를 모두 지웁니다. 다음 빌드는 처음부터 실행되므로 디스크가 급할 때만 씁니다.
재발 방지 및 모범 사례
문제 유형 원인 해결 및 재발 방지 전략 빌드 시간 증가 불필요한 파일 복사, 캐시 무효화 연쇄 .dockerignore사용, Dockerfile 명령어 순서 최적화, 멀티 스테이지 빌드최신 변경 미반영 RUN명령어 캐시가 그대로 재사용됨, 바뀐 파일이 빌드 컨텍스트에 없음apt-get update && install결합,--no-cache또는--pull로 재빌드,.dockerignore에 필요한 파일이 빠졌는지 확인디스크 공간 부족 오래된 빌드 캐시 누적 docker builder prune주기적 실행,--reserved-space설정비효율적인 의존성 관리 매 빌드마다 의존성 재설치 BuildKit 캐시 마운트( --mount=type=cache) 활용,requirements.txt등 의존성 파일 분리정리하면 이렇습니다.
- Dockerfile의 각 레이어 의도 이해: 각 명령어가 어떤 레이어를 생성하고 언제 캐시가 무효화될 수 있는지 정확히 이해해야 합니다.
- BuildKit 기능 활용: 기본 빌더인 BuildKit의 캐시 마운트로 의존성 다운로드를 줄이고,
--progress=plain로그로 캐시가 끊기는 단계를 확인합니다. .dockerignore파일 관리: 빌드 컨텍스트에 포함될 파일을 최소화하여 불필요한 캐시 무효화를 방지합니다.- 멀티 스테이지 빌드 도입: 최종 이미지 크기를 줄이고, 빌드 단계별로 캐시를 효율적으로 관리할 수 있습니다.
- CI/CD 파이프라인에 캐시 전략 통합: CI/CD 환경에서 BuildKit의
--cache-from,--cache-to기능을 활용하여 빌드 시간을 단축합니다.
FAQ
Q.
apt-get update명령어가 캐시되어 최신 패키지를 가져오지 못하는 것 같습니다. 어떻게 해야 하나요?RUN apt-get update명령어가 캐시되면, 실제 패키지 목록이 업데이트되었더라도 Docker는 캐시된 레이어를 재사용할 수 있습니다. 이를 방지하려면RUN apt-get update && apt-get install -y <package>와 같이update와install명령어를 같은 레이어에 두어install명령어가 변경될 때update도 함께 재실행되도록 하거나,docker build --no-cache를 사용하여 모든 캐시를 무시하고 빌드해야 합니다.Q.
ADD나COPY명령어 사용 시 파일의 수정 시간(mtime)이 변경되면 캐시가 무효화되나요?아닙니다. Docker 공식 문서에 따르면
ADD/COPY의 캐시 체크섬 계산에 수정 시간(mtime)은 포함되지 않으므로,mtime만 바뀐 경우에는 캐시가 유지됩니다. 파일 내용이 바뀌면 캐시가 무효화됩니다. 바꾼 파일이 반영되지 않는다면 먼저.dockerignore에서 그 파일이 제외되지 않았는지 확인하세요.Q.
docker build --cache-from과 BuildKit의RUN --mount=type=cache는 동일한 캐시 메커니즘인가요?다릅니다.
--cache-from은 레지스트리 등 외부에 내보낸 레이어 캐시를 가져와 "이 단계를 다시 실행할지"를 판단하는 데 씁니다.RUN --mount=type=cache는 단계가 다시 실행될 때 그 안에서 쓰는 디렉터리(npm, pip, apt 다운로드 캐시 등)를 빌더에 보존하는 기능으로, 이미지 레이어에 포함되지 않고 레지스트리 캐시로 내보내지지도 않습니다.
참고 자료

