• Developer
  • Kubernetes

k3d clusters live inside Docker, so deleting one does not give the space back by itself

k3d runs k3s as Docker containers with their own volumes. How to see what each cluster holds on a Mac, delete it cleanly, and get the space back from Docker.

4 min read

A k3d cluster is a set of Docker containers, a network and a volume named k3d-<cluster>-images. Every image the cluster pulls is stored inside those containers, so it all lands in your Docker engine's virtual disk, not anywhere you would see in Finder.

k3d cluster list
docker ps -a --size --filter "name=k3d-" --format '{{.Names}}\t{{.Size}}'
docker volume ls --filter name=k3d-
docker images 'rancher/k3s'
docker system df

Delete a cluster completely

k3d cluster delete <name>      # or: k3d cluster delete --all

# Volumes left behind by clusters that were removed some other way
docker volume ls -q --filter name=k3d- | xargs docker volume rm

# Old k3s node images
docker images 'rancher/k3s'
docker rmi rancher/k3s:<old-tag>

k3d cluster delete removes the containers, network and volumes it created. Volumes left over from a cluster that was removed with plain docker rm stay until you remove them. docker volume rm refuses a volume that is still in use, which makes the cleanup line above safe to run.

Getting the space back on your Mac

After deleting, docker system df shows less in use, but the Docker virtual disk file on your Mac may not shrink straight away. How to reclaim it depends on whether you use Docker Desktop, Colima or OrbStack: see Docker taking up disk space. For minikube and kind, see local Kubernetes clusters.

Common questions

Does k3d cluster delete remove the volumes?

Yes, it removes the containers, network and volumes k3d created for that cluster. The rancher/k3s node image stays in Docker until you remove it with docker rmi.

Where do k3d images take up space on a Mac?

Inside the Docker engine's virtual disk, because k3d nodes are Docker containers. Clean them with k3d and Docker, then reclaim the virtual disk the way your Docker app supports.

How do I list all k3d leftovers?

Run docker ps -a --filter name=k3d- for containers and docker volume ls --filter name=k3d- for volumes. Anything listed there with no matching cluster in k3d cluster list is a leftover.

Read next