Docker build cache 삭제 방법: docker builder prune 언제 써야 할까

Docker 빌드 캐시는 재빌드를 빠르게 하지만 오래 쌓이면 디스크 용량을 크게 차지할 수 있습니다.

Docker 용량이 계속 늘어난다면 먼저 docker system df로 Build Cache가 원인인지 확인한 뒤, 필요할 때만 docker builder prune으로 빌드 캐시를 삭제하는 것이 안전합니다. 이미지나 볼륨까지 함께 지우는 명령어보다 삭제 범위가 좁기 때문에, 빌드 캐시만 문제일 때 먼저 확인하기 좋은 명령어입니다.

특히 Node.js, Python, Dev Container 프로젝트를 자주 빌드한다면 이미지나 컨테이너를 많이 만들지 않았는데도 디스크 용량이 줄어들 수 있습니다. 빌드 캐시는 다시 만들 수 있는 데이터이지만, 삭제 후 첫 빌드가 느려질 수 있으므로 실행 전 용량과 삭제 범위를 먼저 확인하는 것이 좋습니다.

Docker build cache는 언제 삭제해야 할까

결론부터 말하면 docker system df 결과에서 Build Cache가 크게 보이고, 디스크 용량이 부족하거나 오래된 프로젝트 빌드 기록이 많이 쌓였을 때 삭제하면 됩니다. 매일 습관처럼 지울 필요는 없습니다.

Docker build cache는 Dockerfile 빌드 과정에서 만들어지는 중간 결과입니다. 같은 Dockerfile을 다시 빌드할 때 이전 단계를 재사용해 빌드 시간을 줄여줍니다. 캐시를 지우면 용량은 줄 수 있지만, 다음 빌드는 평소보다 느려질 수 있습니다.

삭제를 고려해도 되는 상황

• Docker Desktop의 디스크 사용량이 계속 늘어나는 경우
• docker system df에서 Build Cache 항목이 크게 보이는 경우
• 예전 프로젝트를 많이 빌드했지만 지금은 사용하지 않는 경우
• Dev Container를 여러 번 rebuild한 뒤 저장공간이 부족해진 경우
• 대형 이미지 빌드 후 노트북 용량이 급격히 줄어든 경우

바로 지우기보다 확인이 먼저인 상황

현재 팀 프로젝트를 계속 빌드하고 있거나, CI와 비슷한 환경을 로컬에서 반복 테스트하고 있다면 전체 캐시 삭제보다 오래된 캐시만 삭제하는 편이 낫습니다. 캐시를 전부 지워도 코드가 삭제되는 것은 아니지만, 다음 빌드 시간이 길어지고 네트워크 다운로드가 다시 발생할 수 있습니다.

먼저 Docker 용량을 확인하는 명령어

빌드 캐시 삭제 전에는 현재 Docker가 어떤 항목에서 용량을 쓰는지 확인해야 합니다. Docker 용량 문제는 빌드 캐시뿐 아니라 이미지, 컨테이너, 볼륨 때문에 생길 수도 있기 때문입니다.

전체 Docker 디스크 사용량 확인

docker system df

이 명령어는 Docker daemon이 사용하는 디스크 용량을 Images, Containers, Local Volumes, Build Cache 같은 항목으로 나누어 보여줍니다. 여기서 Build Cache의 SIZE와 RECLAIMABLE 값을 먼저 확인합니다.

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        5         8.4GB     3.1GB
Containers      4         1         1.2GB     800MB
Local Volumes   6         3         12.5GB    2.0GB
Build Cache     48        0         18.7GB    18.7GB

위와 비슷하게 Build Cache가 크게 보인다면 빌드 캐시 삭제를 검토할 수 있습니다. 반대로 Local Volumes가 크다면 docker builder prune으로는 원하는 만큼 용량이 줄지 않을 수 있습니다.

빌드 캐시를 더 자세히 확인

docker builder du

환경에 따라 docker builder du 대신 Buildx 명령인 docker buildx du가 더 익숙하게 보일 수 있습니다. 이 명령은 빌더가 사용하는 캐시 항목과 회수 가능한 용량을 더 자세히 확인할 때 유용합니다.

docker buildx du

출력에서 RECLAIMABLE이 true인 항목은 정리 대상으로 볼 수 있습니다. 다만 현재 빌더에서 사용 중인 항목은 삭제되지 않거나, 삭제해도 실제 줄어드는 용량이 예상보다 작을 수 있습니다.

docker builder prune 명령어 기본 사용법

docker builder prune은 Docker build cache를 제거하는 명령어입니다. 이미지나 볼륨 정리보다 범위가 좁기 때문에, 빌드 캐시만 문제일 때 먼저 시도하기 좋습니다.

가장 기본적인 빌드 캐시 삭제

docker builder prune

명령을 실행하면 삭제 여부를 묻는 확인 메시지가 나옵니다. 초보자는 -f 옵션을 붙이기보다 확인 메시지를 보고 진행하는 편이 안전합니다.

확인 메시지 없이 실행

docker builder prune -f

-f 또는 --force는 확인 질문 없이 바로 실행하는 옵션입니다. 자동화 스크립트에서는 편하지만, 처음 실행할 때는 권장하지 않습니다.

오래된 캐시만 삭제

docker builder prune --filter "until=24h"

최근 24시간 안에 사용한 캐시는 남기고 오래된 캐시를 정리하고 싶을 때 사용할 수 있습니다. 최근 작업 중인 프로젝트가 있다면 전체 삭제보다 이런 방식이 더 안전합니다.

docker builder prune --filter "until=168h"

168h는 7일입니다. 최근 일주일 안에 사용한 캐시는 남기고 더 오래된 캐시만 정리하려는 상황에 적합합니다.

사용하지 않는 빌드 캐시를 더 넓게 삭제

docker builder prune -a

-a 또는 --all 옵션은 사용하지 않는 빌드 캐시를 더 넓게 정리합니다. 용량 회수 효과는 클 수 있지만, 다음 빌드에서 캐시 재사용이 줄어들 수 있습니다. 디스크가 급하게 부족한 상황이 아니라면 먼저 기본 명령이나 until 필터부터 실행하는 것이 좋습니다.

docker system prune과 docker builder prune 차이

Docker 정리 명령어를 검색하다 보면 docker system prune도 자주 보입니다. 두 명령어는 삭제 범위가 다릅니다. 빌드 캐시만 정리하고 싶다면 docker builder prune부터 보는 것이 안전합니다.

명령어	주요 대상	초보자 기준
docker builder prune	빌드 캐시	Build Cache 용량이 클 때 먼저 사용
docker system prune	중지된 컨테이너, 사용하지 않는 네트워크, dangling 이미지, 빌드 캐시	삭제 범위가 넓으므로 실행 전 출력 내용을 반드시 확인
docker system prune -a	사용하지 않는 이미지까지 더 넓게 정리	다음 실행 때 이미지를 다시 받을 수 있어 주의
docker system prune --volumes	익명 볼륨까지 정리	데이터 삭제 위험이 있어 초보자는 특히 주의

Docker Desktop 전체 용량이 문제라면 이미지, 컨테이너, 볼륨, 빌드 캐시를 순서대로 봐야 합니다. 전체 정리 순서는 하단의 관련 글에서 이어서 확인할 수 있습니다.

Windows, Mac, Linux에서 확인할 차이

Docker 명령어 자체는 비슷하지만, 실제 디스크 용량이 줄어드는 방식은 운영체제와 Docker Desktop 사용 여부에 따라 다르게 느껴질 수 있습니다.

Windows와 WSL2 환경

Windows에서 Docker Desktop을 WSL2 기반으로 사용하면 Docker 데이터가 WSL 가상 디스크 안에 저장될 수 있습니다. 이 경우 캐시를 삭제해도 Windows 탐색기에서 바로 용량이 줄어 보이지 않거나, WSL 가상 디스크 크기 반영이 늦게 느껴질 수 있습니다.

먼저 Docker Desktop을 실행한 상태에서 아래 명령어가 정상 동작하는지 확인합니다.

docker version
docker system df

WSL에서 프로젝트를 열어 빌드하는 경우에는 Windows 터미널, WSL 터미널, VSCode 터미널이 같은 Docker daemon을 보고 있는지도 확인해야 합니다.

Mac Docker Desktop 환경

Mac에서는 Docker Desktop이 내부 디스크 이미지 안에서 Docker 데이터를 관리합니다. 캐시를 지운 뒤 Docker Desktop 화면의 용량 표시가 바로 바뀌지 않을 수 있습니다. 이때는 Docker Desktop을 재시작한 뒤 다시 확인하면 반영 여부를 보기 쉽습니다.

대형 이미지를 자주 빌드하는 Mac 개발환경이라면 프로젝트별로 불필요한 rebuild를 줄이고, 빌드 후 docker system df를 확인하는 습관이 도움이 됩니다.

Linux 환경

Linux에서는 Docker daemon이 직접 시스템의 Docker 저장 경로를 사용합니다. 서버나 회사 장비에서 실행한다면 다른 사용자나 서비스가 같은 Docker daemon을 사용할 수 있으므로, 임의로 prune 명령을 실행하기 전에 운영 중인 컨테이너와 팀 규칙을 확인해야 합니다.

삭제해도 되는 캐시와 조심해야 할 데이터

Docker build cache는 다시 만들 수 있는 데이터에 가깝습니다. 하지만 Docker 안의 모든 데이터가 같은 성격은 아닙니다. 특히 볼륨에는 데이터베이스, 업로드 파일, 개발용 저장 데이터가 들어 있을 수 있습니다.

항목	삭제 전 판단	주의점
Build Cache	대체로 재생성 가능	다음 빌드가 느려질 수 있음
Images	다시 pull 또는 build 가능	네트워크 다운로드가 다시 필요할 수 있음
Stopped Containers	로그나 임시 상태 확인 필요	중지된 컨테이너라도 확인용으로 남겨둔 경우가 있음
Volumes	가장 주의	DB와 파일 데이터가 들어 있을 수 있음

안전한 삭제 순서

처음 정리한다면 한 번에 강한 명령어를 실행하기보다 아래 순서대로 확인하는 것이 좋습니다.

1. docker system df로 전체 용량을 확인합니다.
2. Build Cache가 큰지 확인합니다.
3. docker builder du 또는 docker buildx du로 빌드 캐시 상세 항목을 봅니다.
4. 최근 작업 중인 빌드가 없다면 docker builder prune --filter "until=168h"처럼 오래된 캐시부터 정리합니다.
5. 용량이 여전히 부족하면 docker builder prune 또는 docker builder prune -a를 검토합니다.
6. 삭제 후 다시 docker system df를 실행해 줄어든 용량을 확인합니다.

docker system df
docker buildx du
docker builder prune --filter "until=168h"
docker system df

이 순서대로 실행하면 어떤 항목이 문제였는지 확인하면서 정리할 수 있습니다. 특히 회사 장비나 서버에서는 마지막 단계까지 가기 전에 팀 기준을 확인하는 것이 좋습니다.

재발 방지 방법

Docker build cache는 Docker를 쓰는 동안 자연스럽게 쌓입니다. 완전히 안 쌓이게 하는 것보다, 언제 많이 쌓이는지 알고 주기적으로 확인하는 방식이 현실적입니다.

대형 이미지 빌드 후 확인하기

프레임워크, 브라우저, 머신러닝 패키지, 대형 OS 패키지를 포함한 이미지를 빌드하면 캐시가 크게 늘 수 있습니다. 큰 Dockerfile을 수정한 뒤에는 아래 명령어로 상태를 확인합니다.

docker system df

불필요한 rebuild 줄이기

Dev Container를 사용할 때 설정을 조금씩 바꾸며 반복해서 rebuild하면 빌드 캐시가 빠르게 늘 수 있습니다. Dockerfile과 devcontainer.json 변경은 한 번에 모아서 반영하고, 단순 확장 설치나 VSCode 설정 변경은 컨테이너 rebuild가 필요한 작업인지 먼저 구분하는 것이 좋습니다.

.dockerignore 사용하기

프로젝트 폴더 전체가 빌드 컨텍스트로 들어가면 불필요한 파일까지 빌드에 포함될 수 있습니다. node_modules, 로그 파일, 임시 폴더, 빌드 결과물은 .dockerignore로 제외하는 것이 좋습니다.

node_modules
.git
dist
build
.cache
*.log

공식 자료로 더 확인하기

Docker 정리 명령어는 옵션에 따라 삭제 범위가 달라집니다. 특히 prune 계열 명령은 실행 전 공식 문서에서 현재 옵션 설명을 확인하는 것이 좋습니다.

함께 보면 좋은 글

자주 묻는 질문

Docker build cache 삭제는 docker system df로 Build Cache가 원인인지 확인한 뒤, docker builder prune으로 필요한 범위만 정리하는 것이 가장 안전합니다.