Docker 용량 부족(no space left on device): 삭제 전 확인 순서

Docker에서 no space left on device가 나오면 먼저 부족한 저장소와 공간을 쓰는 대상을 확인해야 합니다. 이 문구만 보고 이미지·컨테이너·볼륨을 한꺼번에 정리하면, 다시 만들 수 있는 빌드 캐시와 보관해야 할 DB 데이터를 구분하지 못합니다.

아래는 Linux 컨테이너를 사용하는 Docker Desktop 또는 Linux Docker Engine에서 확인 범위를 좁히는 순서입니다. 명령은 사용량과 연결 관계를 조회하는 예시이며, 특정 PC의 실제 출력이나 확보한 용량 수치를 제시한 것은 아닙니다.

공간을 쓰는 캐시와 중요한 데이터를 구분하는 AI 생성 설명용 일러스트입니다. 실제 디스크 사용량이나 정리 결과가 아닙니다.

지금 보고 있는 Docker와 오류가 난 곳부터 맞추기

먼저 오류가 난 작업을 구분합니다. 이미지 빌드·다운로드 중인지, 실행 중인 DB가 파일을 쓰던 중인지, 호스트의 공유 폴더에 기록하던 중인지에 따라 확인할 저장소가 다릅니다. 명령을 입력한 PC와 Docker가 실제 실행되는 서버가 다른 경우도 있습니다.

docker context show
docker info --format '{{.Name}} / {{.OperatingSystem}}'
docker system df
docker system df -v

docker context show는 현재 context를, docker info는 연결한 Docker 설치 정보를 확인하는 데 사용합니다. 원격 Docker를 쓰고 있다면 로컬 PC의 디스크만 살펴봐서는 원인을 찾을 수 없습니다. DOCKER_HOST나 명령의 연결 옵션을 따로 쓰는 환경이라면 실제 서버 정보도 함께 맞춥니다.

docker system df는 Docker 데몬이 관리하는 사용량의 요약이고 -v는 상세 정보입니다. 이를 PC 디스크 전체 사용량으로 읽지 않습니다. 이미지끼리 공유하는 데이터도 있으므로 이미지 목록의 크기를 단순히 더한 값과 실제 점유량은 다를 수 있습니다.

Desktop의 가상 디스크와 Linux 파일시스템 구분하기

Docker Desktop이라면 호스트 드라이브의 여유 공간과 Docker의 디스크 사용 제한을 함께 봅니다. Resources 설정의 Disk usage limit·Disk image location은 적용 플랫폼에 따라 표시 여부가 다릅니다. 공식 설정 문서는 해당 항목을 Mac·Linux·Windows Hyper-V 기준으로 설명하므로, Windows WSL 2 환경에 같은 화면이 있다고 가정하지 않습니다. Docker Desktop 리소스 설정을 자신의 백엔드와 맞춰 확인하세요.

Mac에서는 디스크 이미지의 최대 크기와 실제 호스트 디스크 점유량도 구분해야 합니다. 파일 정보에 크게 표시된 숫자가 모두 실제 사용량이라는 뜻은 아닙니다. Docker는 이 차이를 Mac 디스크 이미지 안내에서 설명합니다.

Linux 서버의 Docker Engine이라면 데몬이 실행되는 서버에서 데이터 경로와 파일시스템을 확인합니다.

docker info --format '{{.DockerRootDir}}'
df -h
df -i

df -h는 공간 사용량을, df -i는 파일을 관리하는 inode의 사용량을 보는 명령입니다. 작은 파일이 많이 쌓인 경우에는 남은 바이트만 봐서는 부족합니다. 각 출력에서 Docker 데이터가 놓인 파일시스템을 찾아 읽습니다. 옵션의 의미는 GNU df 매뉴얼을 참고할 수 있습니다.

저장 방식에 따른 예외도 있습니다. Docker Engine 29.0 이후 새 설치의 기본인 containerd 이미지 저장소는 이미지·컨테이너 스냅샷을 별도 경로에 보관합니다. 따라서 DockerRootDir 하나를 Docker의 모든 데이터 위치라고 단정하지 않습니다. Docker 데몬 데이터 디렉터리 안내에서 현재 설치의 저장 방식을 확인합니다.

공간 부족의 위치와 데이터 종류를 나눠 확인하는 설명용 도식입니다. 실제 사용량이나 삭제 결과는 포함하지 않습니다.

큰 항목을 찾은 뒤 다음 조회를 고르기

크게 보이는 항목	다음에 확인할 것	숫자를 읽을 때 주의할 점
Images	docker system df -v의 이미지·참조 정보	공유 레이어가 있으므로 이미지 크기를 단순 합산하지 않기
Containers	docker ps -a --size로 실행·정지 컨테이너 비교	표시된 쓰기 레이어 크기를 볼륨 포함 전체 데이터로 읽지 않기
Local Volumes	어떤 컨테이너에 어떤 목적으로 연결됐는지	미사용 표시와 데이터 불필요는 다른 판단
Build Cache	실제 빌드에 쓴 builder의 캐시	다른 builder의 작은 사용량으로 현재 문제를 배제하지 않기
Docker 항목은 작지만 디스크가 가득 참	호스트 파일·공유 폴더·로그와 실제 오류 경로	Docker 객체 목록에 모든 파일 사용량이 잡힌다고 가정하지 않기

컨테이너를 비교할 때는 다음 명령으로 정지된 것까지 함께 봅니다.

docker ps -a --size

이 명령의 size는 컨테이너 쓰기 레이어, virtual size는 이미지의 읽기 전용 데이터와 쓰기 레이어를 포함하는 값입니다. 볼륨 데이터가 작다는 결론을 여기서 내릴 수는 없습니다. 컨테이너 크기 필드 설명을 기준으로 읽습니다.

빌드 중 발생한 오류라면 Buildx도 확인합니다. 아래 명령은 builder 목록과 현재 선택된 builder의 캐시 사용량을 조회합니다.

docker buildx ls
docker buildx du

builder 목록에서 현재 선택을 확인하고, 실제 빌드에 별도 --builder를 지정했다면 그 대상과 맞춥니다. buildx du의 RECLAIMABLE은 해당 캐시가 정리 대상이 될 수 있는지 보여주는 값이지, 다시 빌드할 때의 비용과 시간을 고려한 추천이 아닙니다.

확인할 builder가 현재 선택과 다르다면 다음처럼 조회 대상만 명시할 수 있습니다. example-builder는 예시이므로 목록에서 확인한 실제 이름으로 바꿉니다. 이 명령은 builder를 만들거나 캐시를 삭제하는 명령이 아닙니다. Buildx의 builder 지정 옵션

docker buildx --builder example-builder du

볼륨과 공유 폴더의 데이터부터 구분하기

DB 데이터가 어디에 저장되는지 모른다면 컨테이너의 마운트 종류부터 확인합니다. 다음의 app은 설명용 컨테이너 이름입니다. 앞서 실행한 docker ps -a의 NAMES 열에서 조회할 이름을 찾아 바꿉니다. Compose 서비스 이름과 실제 컨테이너 이름은 다를 수 있습니다.

docker container inspect --format '{{range .Mounts}}{{.Type}} {{if eq .Type "volume"}}{{.Name}} {{end}}{{.Destination}}{{println}}{{end}}' app

출력은 마운트 종류와 컨테이너 안의 경로를 보여 주며, volume이면 볼륨 이름도 함께 표시합니다. volume은 Docker가 관리하는 볼륨이고, bind는 호스트의 파일이나 폴더를 컨테이너 안으로 연결한 것입니다. 컨테이너 inspect의 상세 정보와 bind mount 설명을 함께 보면 저장 위치의 성격을 구분할 수 있습니다.

연결된 컨테이너가 없더라도 DB 백업이나 다음 실행을 위해 보관한 볼륨일 수 있습니다. 반대로 bind mount의 큰 파일은 호스트 파일을 관리해야 하는 문제일 수 있습니다. “지금 사용 중이지 않음”만으로 삭제 여부를 결정하지 않습니다.

prune은 무엇을 지우는 명령인지 먼저 읽기

정리 명령은 이름이 비슷해도 범위가 다릅니다. 아래 표는 실행을 권하는 목록이 아니라 삭제 범위를 비교한 표입니다.

명령 종류	기본 범위	확인할 조건
docker image prune	태그가 없고 컨테이너가 참조하지 않는 dangling 이미지	-a를 붙이면 컨테이너가 사용하지 않는 이미지까지 넓어짐
docker container prune	정지된 컨테이너	컨테이너 안에만 남은 파일이나 복구에 필요한 상태가 있는지
docker builder prune	dangling 빌드 캐시	-a는 미사용 빌드 캐시까지 포함하며 재빌드 시간이 달라질 수 있음
docker system prune	정지 컨테이너·미사용 네트워크·dangling 이미지·미사용 빌드 캐시	여러 종류가 함께 대상이 됨. 기본값에는 볼륨이 포함되지 않음

범위는 Docker 객체 정리 안내, builder prune 옵션, system prune 옵션에서 확인할 수 있습니다. system prune에 볼륨 옵션을 추가하면 미사용 익명 볼륨까지 범위에 들어갑니다. 데이터 확인 없이 종합 정리나 볼륨 정리를 첫 조치로 삼지 않는 이유입니다.

공간을 회수하기로 했다면 먼저 재생성 가능한 항목과 보존할 항목을 정하고, 필요한 백업·복구 가능성을 확인한 뒤 해당 종류만 검토합니다. 작업 후에는 같은 Docker 대상과 builder에서 사용량을 다시 확인하고, 처음 실패한 작업이 끝나는지도 확인합니다. Docker 안의 회수량과 호스트 디스크에서 보이는 변화가 같은 시점·같은 크기라고 가정하지 않습니다.

이 오류의 첫 해결 단계는 삭제가 아니라 어느 파일시스템이 부족하고, 어떤 데이터가 그 공간을 쓰는지 설명할 수 있는 상태를 만드는 것입니다. 그다음에야 캐시 정리, 불필요한 개별 객체 정리, 저장 공간 확보 중 무엇이 필요한지 선택할 수 있습니다.