Docker 디스크 용량 줄이는 법은 사용량 확인 → 이미지·빌드 캐시 선별 정리 → 볼륨 데이터 검토 순서로 접근하는 것이 좋다. 디스크가 부족하다고 모든 정리 옵션을 한꺼번에 붙이면, 다시 받을 수 있는 이미지와 복구하기 어려운 데이터가 함께 삭제될 수 있다. 먼저 어디에 공간이 쌓였는지 확인하고, 재생성할 수 있는 항목부터 정리하면 판단이 쉬워진다.
📌 핵심 요약
docker system df -v로 공유 레이어, 고유 용량, 컨테이너 참조 상태를 확인한다.docker system prune은 중지된 컨테이너까지 삭제한다. 볼륨은 기본 정리 대상에서 제외된다.-a의 의미는 명령마다 다르다. 이미지 전체 정리, 빌더 내부 이미지 포함, 이름 있는 볼륨 포함을 구분해야 한다.- Docker의 ‘미사용’은 삭제해도 되는 업무 데이터라는 뜻이 아니다. 볼륨은 백업과 복구 확인 후 판단한다.
1. Docker 저장 공간 구성과 회수 가능 용량 확인하기
Docker 저장 공간은 이미지 레이어, 컨테이너의 쓰기 가능한 레이어, 빌드 캐시, 볼륨으로 나누어 살펴볼 수 있다. 이미지를 새로 빌드하거나 컨테이너를 중지해도 관련 자원이 모두 자동 삭제되는 것은 아니다. 그래서 실행 중인 서비스가 적어도 저장 공간은 계속 커질 수 있다.
이미지는 실행 환경을 구성하고, 빌드 캐시는 이전 빌드 결과를 재사용하는 데 쓰인다. 볼륨에는 PostgreSQL 데이터베이스나 애플리케이션 업로드 파일처럼 유지해야 할 데이터가 들어갈 수 있다. 이 차이를 알아야 ‘다시 만들 수 있는 것’과 ‘보존해야 하는 것’을 구분할 수 있다.
docker context show
docker system df
docker system df -v
docker ps -a먼저 현재 Docker 컨텍스트를 확인해 정리할 환경이 맞는지 점검한다. 이어 요약 출력의 SIZE와 RECLAIMABLE을 비교하고, 상세 출력에서 어떤 이미지와 볼륨이 공간을 차지하는지 확인한다. 원격 Docker 환경을 사용 중이라면 명령이 로컬 컴퓨터가 아닌 연결된 서버에 적용될 수 있다는 점도 확인해야 한다.
RECLAIMABLE은 Docker가 회수 가능하다고 계산한 용량이며, 기본 정리 명령 하나로 반드시 확보되는 공간은 아니다. 삭제 옵션과 공유 레이어 상태에 따라 실제 결과가 달라진다. 이미지 상세 출력의 SIZE는 SHARED SIZE와 UNIQUE SIZE의 합계이므로, 이미지별 SIZE를 단순히 더하면 공유 데이터를 중복 계산할 수 있다. [Docker 공식 용량 확인 문서](https://docs.docker.com/reference/cli/docker/system/df/)
Docker 공식 문서의 예시에서는 이미지 사용량이 16.43 MB, 회수 가능 용량이 11.63 MB, 70%로 표시된다. 이는 문서의 설명용 출력이며 실제 환경의 평균이나 2026년 사용 통계가 아니다. 같은 문서의 alpine:3.3 예시는 SIZE가 4.797 MB지만 UNIQUE SIZE는 0 B여서, 표시된 이미지 크기만 보고 삭제 효과를 예상하기 어렵다는 점을 보여준다. [Docker 공식 출력 예시](https://docs.docker.com/reference/cli/docker/system/df/)
1. Docker 저장 공간 구성과 회수 가능 용량 확인하기
2. 이미지·빌드 캐시·볼륨 삭제 여부 판단표
용량이 큰 항목부터 무조건 지우기보다, 재생성 가능성과 데이터 보존 필요성을 함께 확인하는 편이 좋다. 아래 표의 명령은 선택 가능한 정리 방법이며, 위에서 아래로 모두 실행하는 순서가 아니다. 특히 중지된 컨테이너와 미사용 볼륨은 앞으로 다시 사용할 계획이 있는지 먼저 검토해야 한다.
| 정리 대상 | 명령과 삭제 범위 | 삭제 전 판단 기준 |
|---|---|---|
| Dangling 이미지 | docker image prune태그가 없고 컨테이너가 참조하지 않는 이미지 |
이미지 ID로 보관하던 결과물이 필요한지 확인 |
| 미사용 태그 이미지 | docker image prune -a기존 컨테이너가 참조하지 않는 이미지까지 포함 |
레지스트리에서 다시 받거나 재빌드할 수 있는지 확인 |
| 빌드 캐시 | docker buildx prune선택한 빌더의 정리 가능한 캐시 |
다음 빌드에서 재다운로드·재컴파일할 여유가 있는지 확인 |
| 중지된 컨테이너 | docker container prune모든 중지된 컨테이너 |
쓰기 레이어에만 저장한 파일과 재시작 계획 확인 |
| 미사용 익명 볼륨 | docker volume prune컨테이너가 참조하지 않는 익명 로컬 볼륨 |
익명 볼륨에도 보존할 데이터가 없는지 확인 |
| 미사용 이름 있는 볼륨 | docker volume prune -a미사용 이름 있는 로컬 볼륨까지 포함 |
백업·복구 가능 여부 확인, API 1.42 이상 필요 |
이미지·컨테이너 정리 범위는 Docker의 자원 정리 안내를, 볼륨의 기본 범위와 API 조건은 전용 CLI 문서를 기준으로 구분했다. 실행 중인 컨테이너뿐 아니라 중지된 컨테이너의 참조도 이미지와 볼륨의 삭제 여부에 영향을 준다. [Docker 자원 정리 안내](https://docs.docker.com/engine/manage-resources/pruning), [Docker 볼륨 정리 문서](https://docs.docker.com/reference/cli/docker/volume/prune/)
2. 이미지·빌드 캐시·볼륨 삭제 여부 판단표 바로가기
3. Docker 이미지 정리와 system prune 옵션 구분하기
이미지만 정리하려면 docker image prune부터 검토한다. 태그가 있는 이미지까지 지우려면 -a가 필요하지만, 기존 컨테이너가 참조하는 이미지는 대상에서 제외된다. 따라서 ‘현재 실행 중이지 않다’와 ‘어떤 컨테이너도 참조하지 않는다’는 다른 조건이다. [Docker 이미지 정리 안내](https://docs.docker.com/engine/manage-resources/pruning)
# 이미지 정리: 필요한 범위 하나를 선택
docker image prune
docker image prune -a여러 자원을 한 번에 정리하는 docker system prune은 중지된 컨테이너, 미사용 네트워크, dangling 이미지, 미사용 빌드 캐시를 삭제한다. 기본 명령에는 볼륨 삭제가 포함되지 않지만, 중지된 컨테이너의 쓰기 레이어는 삭제되므로 보존할 파일이 있는지 확인해야 한다. [Docker 시스템 정리 문서](https://docs.docker.com/reference/cli/docker/system/prune/)
# 기본 범위 정리
docker system prune
# 미사용 태그 이미지까지 포함
docker system prune -a
# 미사용 익명 볼륨까지 포함: 데이터 검토 후 선택
docker system prune --volumes
# 위 두 옵션을 함께 적용: 가장 넓은 범위를 검토
docker system prune -a --volumesdocker system prune -a --volumes도 이름 있는 볼륨 전체를 삭제하는 명령은 아니다. 여기서 -a는 이미지 정리 범위를 넓히고, --volumes는 미사용 익명 볼륨을 추가한다. 또한 컨테이너 삭제 후 참조가 사라질 수 있으므로, 실행 전부터 미사용이던 항목만 영향을 받는다고 생각해서는 안 된다. [Docker 시스템 정리 옵션](https://docs.docker.com/reference/cli/docker/system/prune/)
시간 조건을 붙인 docker system prune --filter "until=24h"에서는 컨테이너·이미지·네트워크의 생성 시점을 기준으로 범위를 제한한다. ‘최근 24시간 동안 사용하지 않았다’는 뜻으로 해석하면 안 된다. -f는 확인 질문을 생략하므로 수동 점검 단계에서는 붙이지 않고 삭제 범위 안내를 읽는 편이 좋다. [Docker 시스템 정리 필터](https://docs.docker.com/reference/cli/docker/system/prune/)
3. Docker 이미지 정리와 system prune 옵션 구분하기
4. Buildx 빌드 캐시 정리와 용량 제한 옵션 활용하기
반복 빌드가 많은 환경에서는 이미지 목록과 별개로 빌더 캐시를 확인할 필요가 있다. Buildx는 선택한 빌더의 캐시를 정리하므로, 여러 빌더를 사용한다면 어느 빌더를 대상으로 하는지 먼저 확인한다. 빌더별로 캐시가 따로 유지된다는 점은 2026년 현재 Docker 공식 정리 안내에서도 명시하고 있다. [Docker 빌드 캐시 정리 안내](https://docs.docker.com/engine/manage-resources/pruning)
docker buildx ls
docker buildx du
# 최근 24시간 동안 사용한 캐시를 보존하는 정리
docker buildx prune --filter "until=24h"
# 별도 정책 예시: 캐시 최대 사용량을 2gb로 설정해 정리
docker buildx prune --max-used-space 2gb
# 별도 정책 예시: 정리 후 여유 공간 목표를 2gb로 설정
docker buildx prune --min-free-space 2gbBuildx의 until=24h는 최근 24시간 동안 사용한 캐시를 보존하는 조건이다. --max-used-space는 캐시 최대 사용량을, --min-free-space는 정리 후 목표 여유 공간을 지정한다. Docker 문서가 제시하는 단위 표기는 128mb·2gb이며, 정리 조건에 따라 가장 오래 사용하지 않은 캐시부터 삭제한다. [Docker Buildx 정리 옵션](https://docs.docker.com/reference/cli/docker/buildx/prune/)
위의 2gb는 문서에서 지원하는 표기를 활용한 정책 예시이며 모든 프로젝트의 권장값은 아니다. 보존 조건과 삭제 가능한 캐시의 양에 따라 목표 공간을 확보하지 못할 수도 있다. docker buildx prune --all은 내부 도우미 이미지와 프런트엔드 이미지도 범위에 포함하므로, 일반 이미지 정리의 -a와 같은 의미로 받아들이지 않아야 한다. [Docker Buildx 옵션 설명](https://docs.docker.com/reference/cli/docker/buildx/prune/)
운영 관점에서는 캐시를 전부 비우는 것보다 빌드 빈도에 맞춘 보존 기준이 유용하다. 디스크 회수 효과와 다음 빌드의 재다운로드·재컴파일 부담을 함께 평가해야 하기 때문이다. 자주 사용하는 캐시를 남기고 오래 쓰지 않은 캐시부터 줄이는 방식은 작업 속도와 저장 공간 사이의 균형을 잡는 데 도움이 된다.
4. Buildx 빌드 캐시 정리와 용량 제한 옵션 활용하기
5. Docker 볼륨 정리 전 데이터 보존 체크리스트
볼륨의 ‘미사용’은 어떤 컨테이너도 참조하지 않는다는 뜻이다. 프로젝트를 잠시 내려둔 뒤 남은 데이터베이스 볼륨도 미사용 상태가 될 수 있으므로, 이 상태만으로 삭제를 결정하면 안 된다. 익명 볼륨과 이름 있는 볼륨 모두 실제 저장 내용과 복구 가능성을 기준으로 판단해야 한다.
docker volume ls
docker volume inspect 볼륨이름
docker ps -a --filter volume=볼륨이름
docker inspect 컨테이너이름위 명령의 ‘볼륨이름’과 ‘컨테이너이름’은 실제 대상으로 바꾼다. 컨테이너 상세 정보의 Mounts에서는 마운트 유형과 연결 위치를 확인할 수 있다. 다만 볼륨 메타데이터와 참조 목록만으로 안에 들어 있는 데이터의 업무 가치를 판단할 수는 없으므로, 프로젝트 설정과 데이터 용도를 함께 살펴야 한다.
- Docker Compose 설정에서 서비스와 볼륨의 연결 관계를 확인한다.
- 데이터베이스, 업로드 파일, 재사용할 작업 결과물이 저장되어 있는지 확인한다.
- 데이터베이스는 해당 제품의 백업 방식에 맞춰 일관성 있는 백업을 만든다.
- 백업 파일이 존재하는지 확인하고, 별도 환경에서 복원 가능한지 검증한다.
- 용도를 모르는 볼륨은 보존하고, 삭제 대상으로 확인한 항목만 정리한다.
docker volume prune은 기본적으로 미사용 익명 로컬 볼륨을 정리한다. API 1.42 이상에서 지원하는 -a 또는 --all을 붙이면 미사용 이름 있는 볼륨도 포함된다. 볼륨 정리가 필요하다면 docker version으로 서버 API 버전을 확인하고, 실행 시 표시되는 삭제 안내도 읽어야 한다. [Docker 볼륨 정리 CLI 문서](https://docs.docker.com/reference/cli/docker/volume/prune/)
label이다. 이미지나 Buildx의 until=24h 조건을 볼륨에도 그대로 적용할 수 있다고 생각하면 안 된다. 라벨 역시 데이터 보존 여부를 자동으로 보장하지 않으므로, 삭제 허용 대상과 백업 상태를 먼저 확인해야 한다. [Docker 볼륨 필터 문서](https://docs.docker.com/reference/cli/docker/volume/prune/)
이미지와 캐시는 재생성 경로를 확보하면 삭제 비용을 예측하기 쉽지만, 볼륨은 데이터 손실 비용이 중심이다. 따라서 정리 자동화를 설계할 때도 두 대상을 같은 기준으로 묶기 어렵다. 컨테이너를 지운 뒤 볼륨까지 연속 정리하는 절차는, 참조가 사라진 데이터가 곧바로 삭제 대상이 될 수 있다는 점을 별도로 검토해야 한다.
5. Docker 볼륨 정리 전 데이터 보존 체크리스트 조회하기
6. 정리 후 용량 재확인과 macOS Docker Desktop 주의점
선택한 정리 명령이 끝나면 처음과 같은 기준으로 사용량을 다시 확인한다. 명령 출력의 Total reclaimed space, Docker 내부 사용량, 운영체제의 여유 공간을 함께 비교하면 정리 효과를 더 정확히 파악할 수 있다. 한 번에 모든 항목을 삭제하는 것보다 대상별로 정리하고 결과를 확인하면 어떤 자원이 공간 증가의 원인이었는지도 찾기 쉽다.
docker system df
docker system df -v
docker buildx dumacOS용 Docker Desktop에서는 디스크 이미지의 최대 크기와 실제 점유 공간을 구분해야 한다. Docker 공식 문서의 예시는 최대 크기가 64 GB지만 실제 사용량은 2,333,548 KB로 표시되는 경우를 보여준다. 파일의 최대 크기만 보고 그 전체가 디스크를 차지한다고 판단하면 정리 효과를 잘못 해석할 수 있다. [Docker Desktop Mac 디스크 사용량 안내](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/)
Docker Desktop 설정의 Resources → Advanced에서 디스크 이미지 위치와 최대 크기, 실제 사용량을 확인할 수 있다. 호스트에 여유 공간이 반영되기까지 몇 분이 걸릴 수 있으므로 정리 직후 수치만 보고 다시 대량 삭제할 필요는 없다. 특히 최대 디스크 이미지 크기를 줄이면 기존 디스크 이미지가 삭제되어 모든 컨테이너와 이미지가 사라진다. 이 설정 변경은 일반적인 자원 정리와 구분해 다뤄야 한다. [Docker Desktop Mac 디스크 설정 안내](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/)
먼저 docker system df -v로 공간 구성을 확인하고, 재생성 가능한 이미지와 빌드 캐시부터 필요한 범위만 정리한다. 중지된 컨테이너는 저장 파일을, 볼륨은 데이터 용도와 백업·복구 상태를 확인한 뒤 삭제한다. 마지막으로 같은 명령으로 사용량을 다시 측정하면 데이터 보존과 용량 회수를 함께 관리할 수 있다.