Limpiar Docker en Mac sin perder datos

Docker Desktop puede ocupar decenas de gigabytes porque las imágenes, las capas escribibles de los contenedores, la caché de build y los volúmenes viven dentro de un disco virtual de Linux. Esas categorías no se pueden borrar con la misma tranquilidad. La caché de build suele ser reproducible; un volumen de base de datos puede ser la única copia de datos importantes. Una limpieza segura empieza por el inventario de Docker, no por su comando de prune más amplio.

Por qué el espacio de Docker no vuelve solo

Docker Desktop en macOS ejecuta una VM de Linux y normalmente guarda sus datos en un disco virtual sparse llamado Docker.raw. La guía de almacenamiento en Mac de Docker indica Docker Desktop > Settings > Resources > Advanced para ver su ubicación, el límite de disco y el espacio real que consume. Muévelo con ese control, no con Finder. Un archivo sparse tiene un tamaño lógico máximo y una asignación física más pequeña, así que solo con ls -lh puede parecer mucho más grande de lo que realmente ocupa en ese momento.

Mira cuánto espacio cree Docker que está usando:

docker system df -v

La vista detallada desglosa imágenes, contenedores, volúmenes locales y caché de build. "Reclaimable" significa que Docker no ve ninguna referencia actual que requiera ese objeto; no demuestra que no vayas a necesitar mañana un contenedor detenido, una imagen antigua o un volumen. Revisa también docker ps -a y docker volume ls antes de hacer prune.

Empieza con limpiezas acotadas

Siempre recupera espacio desde dentro de Docker, no borrando el archivo del disco virtual. Empieza por la categoría que entiendes:

docker builder prune --filter until=168h
docker image prune
docker container prune

El primer comando elimina la caché de build de más de siete días; ajusta la antigüedad a tu flujo de trabajo. Los dos siguientes piden confirmación antes de quitar imágenes dangling y contenedores detenidos. Vuelve a ejecutar docker system df -v después de cada paso para ver qué acción tuvo efecto.

La guía de pruning de Docker documenta docker system prune como un comando de conveniencia más amplio. Añadir -a elimina todas las imágenes no usadas, no solo las capas dangling. Añadir --volumes amplía la operación a volúmenes anónimos no usados, que pueden contener archivos de base de datos u otro estado. No conviertas docker system prune -a --volumes en tu comando de limpieza por defecto. Antes de cualquier prune de volúmenes, inspecciona nombres y propiedad:

docker volume ls
docker volume inspect <volume-name>

Los volúmenes creados por Compose suelen llevar etiquetas de proyecto y de servicio. Identifica el proyecto al que pertenecen y exporta o respalda los datos que no se puedan reconstruir antes de eliminar el volumen.

Recuperar el espacio de la imagen de disco

Después de un prune, los bloques libres existen dentro del sistema de archivos de Linux antes de que macOS necesariamente los reciba del disco sparse. La documentación actual de Docker indica que una imagen Docker.raw normalmente devuelve el espacio elegible del host en segundos; las imágenes antiguas Docker.qcow2 usan un proceso en segundo plano que puede tardar minutos. Vuelve a medir el uso real del disco en lugar de juzgar por el máximo lógico del archivo. Un factory reset no es compactación: destruye contenedores locales, imágenes, volúmenes y ajustes. Úsalo solo cuando esa pérdida total sea intencional y los datos importantes de los volúmenes ya se hayan exportado.

Bajo el capó: por qué el archivo crece y no se encoge

Docker Desktop ejecuta una VM de Linux, y Docker.raw es el disco virtual de esa VM: un archivo sparse que crece cuando el guest escribe, pero no devuelve espacio a macOS de forma automática cuando el guest borra. Al eliminar una imagen, los bloques se marcan libres dentro del sistema de archivos de la VM, pero el archivo en el host solo se reduce si el guest emite TRIM/discard y Docker Desktop puede usar discard y compactación para devolver los bloques elegibles. El tiempo depende de su versión y de la implementación de la imagen de disco. Por eso una limpieza lógica y el cambio de capacidad a nivel del host hay que medirlos por separado, y por eso borrar el archivo en el host equivale a destruir todo el entorno de Docker.

Dónde ayuda un mapa de disco

Un mapa de disco como la vista Analyze de Mole puede revelar el disco virtual y su huella física. El propio CLI de Docker debe decidir qué objetos internos están referenciados. Las dos vistas responden preguntas distintas: macOS muestra dónde está asignada la capacidad, mientras Docker explica qué contiene esa asignación.

Un orden seguro de operaciones

Ejecuta docker system df -v, identifica proyectos antiguos y volúmenes con estado, exporta los datos únicos y haz prune de una categoría a la vez. Vuelve a comprobar tanto los totales internos de Docker como la capacidad física de macOS. Usa flags amplios de prune solo después de revisar su alcance ampliado, y nunca uses un factory reset como atajo rutinario para recuperar espacio. La ganancia segura más rápida suele ser la caché de build antigua, no volúmenes desconocidos.