Docker 용량이 부족할 때, 이미지·빌드 캐시·볼륨 중 무엇부터 정리할까?

빌드 중에 저장공간이 부족하다는 메시지가 뜨면, 검색창에 Docker 정리 명령부터 입력하게 됩니다. 이때 한 번에 많이 지우는 명령을 고르기보다 용량을 차지하는 것이 빌드 캐시인지, 이미지인지, 데이터 볼륨인지 먼저 구분하세요. 다시 만들 수 있는 파일과 데이터베이스 내용은 같은 방식으로 다루기 어렵습니다.

이 글은 사용량 확인 → 대상별 정리 → 볼륨 별도 검토 순서로 설명합니다. 명령은 현재 선택된 Docker 환경에 적용되므로, 여러 서버나 컨텍스트를 오가는 사람은 첫 줄부터 확인하는 편이 좋습니다.

캐시와 이미지도 재생성 비용이 있고, 볼륨에는 다시 만들 수 없는 데이터가 남아 있을 수 있습니다.

지우기 전에 사용량과 연결된 환경을 확인합니다

docker context show
docker system df
docker system df -v

docker context show로 적용할 환경을 확인한 뒤 docker system df를 봅니다. Images·Containers·Local Volumes·Build Cache 가운데 어느 항목이 큰지 살피고, -v로 이미지의 공유 크기와 고유 크기를 구분합니다. 이미지 여러 개가 같은 레이어를 공유하면 표시된 크기를 단순히 더한 값과 실제 회수 공간이 다를 수 있습니다.

RECLAIMABLE은 Docker가 정리할 수 있는 공간을 판단하는 데 도움을 주지만, 업무상 필요 없는 데이터라는 뜻은 아닙니다. 한동안 연결하지 않은 DB 볼륨이나 나중에 다시 쓸 중지 컨테이너도 있을 수 있습니다.

빌드 캐시가 크면 캐시부터 따로 봅니다

반복 빌드가 많았다면 캐시가 큰 비중을 차지할 수 있습니다. docker builder prune은 빌드 캐시를 정리하는 명령입니다. 확인 메시지를 읽고 진행하세요. 컨테이너와 볼륨까지 한꺼번에 정리할 필요는 없습니다.

docker builder prune

캐시를 지우면 다음 빌드에서 필요한 단계를 다시 실행하므로 빌드가 느려지고 다운로드가 늘어날 수 있습니다. Buildx의 여러 빌더를 사용한다면 docker buildx ls로 대상을 보고, docker buildx du가 현재 선택된 빌더의 사용량을 보여 준다는 점도 확인하세요.

이미지와 중지 컨테이너는 사용 계획을 보고 고릅니다

docker image ls
docker ps -a
docker image prune

마지막 줄은 기본적으로 dangling 이미지를 정리합니다. 반면 docker image prune -a는 컨테이너에서 사용하지 않는 이미지까지 범위를 넓힙니다. 태그가 있다는 이유만으로 남는 것은 아닙니다. 다음 실행에 다시 내려받을 수 있는 이미지인지, 로컬에서만 만든 이미지인지 먼저 확인하세요.

중지 컨테이너도 바로 쓰레기라고 볼 수 없습니다. 컨테이너의 쓰기 가능한 파일 계층에만 남아 있는 파일은 컨테이너를 지우면 함께 잃을 수 있습니다. 필요한 내용을 확인한 뒤 특정 대상을 삭제하는 편이 판단하기 쉽습니다.

docker system prune은 기본적으로 중지 컨테이너, 사용하지 않는 네트워크, dangling 이미지, 빌드 캐시를 함께 정리합니다. 단순히 ‘이미지만 정리하는 명령’으로 이해하면 안 됩니다. 기본값은 볼륨을 지우지 않지만, 그렇다고 다른 작업 데이터가 모두 보존되는 것도 아닙니다.

볼륨은 연결 상태와 데이터부터 확인합니다

볼륨에는 PostgreSQL·MySQL 데이터나 업로드 파일이 들어 있을 수 있습니다. 아래의 example_db_data는 설명용 이름입니다. 실제 목록에서 확인한 이름으로 바꿔 연결 상태와 저장 대상을 살펴보세요.

docker volume ls
docker volume inspect example_db_data
docker ps -a --filter volume=example_db_data

여기서는 실행 중인 컨테이너만 보지 않고 -a로 중지된 컨테이너도 포함합니다. 공식 volume prune 설명에서 미사용 볼륨은 어떤 컨테이너도 참조하지 않는 볼륨입니다. 지금 컨테이너가 없더라도 다음 실행에 다시 붙여 쓸 데이터가 남아 있을 수 있습니다.

이름이 비슷해도 정리 범위가 다릅니다

옵션	볼륨에 미치는 영향
docker system prune	기본값으로 볼륨을 정리하지 않습니다.
docker system prune --volumes	미사용 익명 볼륨도 정리합니다.
docker volume prune	기본값은 미사용 익명 볼륨입니다.
docker volume prune -a	미사용 명명 볼륨까지 포함합니다.

system prune -a의 -a는 이미지 범위를 넓히는 옵션입니다. volume prune -a와 같은 뜻으로 읽으면 안 됩니다. 또한 익명 볼륨이라고 데이터가 덜 중요한 것도 아닙니다. 이름의 유무와 데이터의 가치는 별개입니다.

이 차이는 직접 만든 빈 볼륨 두 개로 확인했습니다. Docker CLI 29.4.1·Engine 29.2.1에서 고유 라벨로 실험 대상만 제한했을 때, 기본 volume prune은 익명 볼륨만 지웠고 명명 볼륨은 남았습니다. 이어서 같은 라벨에 --all을 적용하자 명명 볼륨도 삭제됐습니다. 기존 작업 볼륨이나 전체 시스템을 정리한 실험은 아닙니다.

실제 데이터 볼륨은 사용 목적과 백업·복구 가능성을 확인한 뒤 개별 대상을 판단하세요. 정리 명령에 확인 절차를 건너뛰는 -f를 습관처럼 붙이는 것은 피하는 편이 좋습니다.

Mac에서 Docker.raw가 그대로 커 보여도 확인할 값이 다릅니다

Docker Desktop for Mac은 컨테이너와 이미지를 큰 디스크 이미지 파일 안에 저장합니다. 공식 Mac FAQ에 따르면 일부 도구는 이 파일이 실제로 차지하는 공간 대신 최대 크기를 표시할 수 있습니다. 정리 뒤에는 Docker Desktop 설정의 실제 사용량과 호스트 여유 공간을 함께 비교하세요.

파일이 커 보인다는 이유로 Docker.raw를 직접 삭제하거나 디스크 이미지 크기를 무작정 줄이지 마세요. 공식 문서는 최대 크기를 줄이는 과정에서 기존 디스크 이미지와 컨테이너·이미지가 삭제된다고 안내합니다. 캐시 몇 개를 정리하는 작업과는 영향이 다릅니다.

먼저 사용량에서 가장 큰 항목 하나를 고르고, 그 항목에 맞는 명령을 검토한 뒤 다시 docker system df를 비교하세요. 어떤 데이터가 사라졌는지 설명할 수 있을 만큼 나눠서 정리하면 다음 작업도 이어가기 쉽습니다.

확인 기준: 2026년 10월 9일. 삭제 동작은 빈 테스트 볼륨에 한해 검증했습니다. 실제 DB 복구, 대용량 디스크 회수량과 Mac의 회수 시간은 이 글에서 측정하지 않았습니다.