지니제스트 테크 블로그 배너
지니제스트Tech Archive
Docker8분 소요

Docker 빌드 캐시가 무효화되는 원인과 빌드 속도 개선

•
지지니제스트
•조회 3

Docker 빌드가 매번 처음부터 도는 이유를 --progress=plain 로그에서 CACHED가 끊기는 지점으로 찾고, COPY 순서, .dockerignore, 캐시 마운트, 레지스트리 캐시, builder prune으로 고치는 방법을 정리했습니다.

Docker 빌드 캐시가 무효화되는 원인과 빌드 속도 개선

코드 한 줄만 고쳤는데 npm install이나 pip install 단계가 매번 처음부터 도는 경우가 있습니다. 반대로 apt-get update가 오래된 결과로 캐시돼 새 패키지가 설치되지 않기도 합니다. 둘 다 원인은 같습니다. 빌드 캐시는 Dockerfile 명령어를 위에서 아래로 비교하고, 한 단계라도 달라지면 그 아래를 전부 다시 실행하기 때문입니다.

로그에서 캐시가 끊긴 첫 단계를 찾고, 그 단계의 입력이 왜 바뀌었는지 보는 순서로 풀어 갑니다.

빌드 로그에서 CACHED가 처음 사라진 단계를 찾아 입력 변경을 확인하고 COPY 순서·캐시 마운트·레지스트리 캐시로 고치는 순서
캐시가 끊긴 단계를 찾고 고치는 순서


빌드 캐시 문제 증상과 원인 진단

Docker 이미지 빌드 시 캐시 문제가 발생하면 주로 다음과 같은 증상을 보입니다.

  • 빌드 시간 증가: 빌드 로그에서 CACHED 표시 없이 다시 실행되는 단계가 많고, 바꾼 적 없는 의존성 설치 단계까지 매번 처음부터 실행됩니다.
  • 최신 변경 사항 미반영: apt-get update나 npm install과 같은 명령어가 캐시되어 최신 패키지나 의존성이 설치되지 않는 경우가 있습니다. 또는 ADD나 COPY 명령어로 추가한 파일이 업데이트되지 않는 것처럼 보일 수 있습니다.

이러한 증상을 진단하려면 빌드 로그에서 캐시가 끊긴 첫 단계를 찾아야 합니다. Docker Engine 23.0부터 Linux의 기본 빌더는 BuildKit이고, BuildKit은 캐시를 재사용한 단계에 CACHED 를 붙입니다. 단계별 로그를 한 줄씩 보려면 --progress=plain 을 붙여 빌드합니다.

BASH
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 명령어의 파일 변경: 빌더는 복사 대상 파일의 메타데이터로 캐시 체크섬을 계산하고, 관련 파일 중 하나라도 바뀌면 해당 명령어의 캐시를 무효화합니다.
⚠️ 수정 시간(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 환경 변수를 지정할 수 있습니다.

BASH
DOCKER_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 으로 가져와 재사용할 수 있습니다.

BASH
docker 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 로 별도 빌더를 만들어 사용해야 합니다.

note[BuildKit 내부 캐시와 `--cache-from`의 차이점] `--cache-from`/`--cache-to` 는 레이어 캐시(각 단계를 다시 실행할지 판단하는 캐시)를 빌드 환경 밖으로 내보내고 가져오는 기능입니다. 캐시 마운트(`--mount=type=cache`)는 단계가 다시 실행될 때 그 안에서 쓰는 디렉터리(패키지 다운로드 캐시 등)를 빌더에 남겨 두는 기능이며, 레지스트리 캐시로 내보내지지 않습니다. :::

Dockerfile 최적화 전략

캐시 효율성을 극대화하기 위한 Dockerfile 작성 모범 사례는 다음과 같습니다.

명령어 순서 최적화

Dockerfile에서 자주 변경되지 않는 명령어를 상단에 배치하고 자주 변경되는 명령어를 하단에 배치하여 캐시 재사용률을 높일 수 있습니다. 캐시 무효화는 해당 레이어부터 아래로 전파되기 때문입니다.

나쁜 예입니다.

DOCKERFILE
FROM python:3.13-slim
WORKDIR /app
# 코드가 바뀔 때마다 이 단계부터 아래 단계가 모두 다시 실행된다
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

좋은 예입니다.

DOCKERFILE
FROM 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 플래그를 사용하면 모든 빌드 캐시를 비활성화하고 모든 레이어를 처음부터 다시 빌드합니다. 이는 캐시로 인해 발생하는 문제를 완전히 회피하고 싶을 때 유용합니다.

BASH
docker build --no-cache -t my-image .

베이스 이미지까지 최신 버전으로 다시 가져오려면 --pull 플래그를 함께 사용할 수 있습니다.

BASH
docker build --no-cache --pull -t my-image .

docker builder prune 명령어를 이용한 BuildKit 캐시 정리

docker builder prune 명령어를 사용하여 BuildKit 캐시를 수동으로 정리할 수 있습니다. 이는 디스크 공간을 확보하는 데 도움이 됩니다.

  • 오래된 캐시 제거: --filter "until=168h" 옵션으로 168시간(7일)보다 오래된 캐시를 제거할 수 있습니다.

    BASH
    docker builder prune --filter "until=168h"
  • 일정 용량만 남기고 정리: --reserved-space 를 주면 캐시를 지정한 크기만큼은 남기고, 그보다 많으면 오래 쓰지 않은 캐시부터 지웁니다. 명령을 실행할 때 한 번 정리하는 것이며 상시 제한이 걸리는 것은 아닙니다. 이 옵션은 최신 Docker CLI 기준이고, 이전 버전에서는 같은 역할의 --keep-storage 를 씁니다.

    BASH
    docker 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 다운로드 캐시 등)를 빌더에 보존하는 기능으로, 이미지 레이어에 포함되지 않고 레지스트리 캐시로 내보내지지도 않습니다.


참고 자료