“docker system prune” vs “docker volume prune”: “no space left on device” solución definitiva

Si de repente tus builds de Docker empiezan a fallar con:

write /var/lib/docker/tmp/...: no space left on device

o docker-compose up se queda a medias con errores de escritura, casi seguro que Docker se ha comido todo el espacio disponible en disco — es uno de los problemas más comunes en máquinas de desarrollo que llevan meses construyendo imágenes sin limpieza. La buena noticia es que Docker incluye herramientas de limpieza muy potentes; la mala es que si no sabes exactamente qué limpia cada una, puedes borrar cosas que necesitabas conservar.

Ya cubrimos los comandos básicos de limpieza (y cómo reubicar el directorio raíz de Docker o desinstalarlo por completo) en Cómo limpiar el espacio ocupado por Docker. Este artículo va un paso más allá: se centra específicamente en la diferencia de riesgo entre system prune y volume prune, que es donde de verdad se puede perder información sin darte cuenta.

Contenidos

Paso 1: confirmar que el problema es realmente Docker
docker system prune: qué borra exactamente
docker volume prune: el que hay que usar con más cuidado
El combo que libera más espacio de golpe
Configurar límites para que no vuelva a pasar
Si usas Docker Desktop en Windows/Mac con WSL2
Verificación final
Resumen

Paso 1: confirmar que el problema es realmente Docker

Antes de lanzar comandos de limpieza a ciegas, confirma cuánto espacio está usando Docker realmente:

docker system df

Esto te da un resumen por categoría:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          47        12        18.2GB    14.8GB (81%)
Containers      23        3         340MB     280MB (82%)
Local Volumes   15        4         6.1GB     3.2GB (52%)
Build Cache     128       0         9.8GB     9.8GB (100%)

Fíjate especialmente en la columna RECLAIMABLE — es el espacio que puedes recuperar sin tocar nada que esté activamente en uso. Si ves que el Build Cache ocupa varios GB con un 100% reclamable, ese suele ser el mayor culpable en máquinas de desarrollo que hacen muchos docker build.

`docker system prune`: qué borra exactamente

docker system prune

Este comando limpia, sin tocar volúmenes:

Todos los contenedores parados (docker container prune).
Todas las redes no usadas por ningún contenedor (docker network prune).
Todas las imágenes dangling (imágenes intermedias sin tag, resultado de builds anteriores que quedaron huérfanas).
Toda la caché de build no utilizada.

Lo que NO borra por defecto: imágenes con tag que no estén en uso por ningún contenedor activo, ni volúmenes con datos. Esto es importante — si tienes una imagen mi-app:v1.2 que no tiene ningún contenedor corriendo ahora mismo, docker system prune a secas no la borra, precisamente para evitar que pierdas una imagen que quizás vayas a necesitar mañana.

Para forzar también el borrado de imágenes con tag no usadas, necesitas el flag -a:

docker system prune -a

Cuidado con este flag — con -a, cualquier imagen que no tenga un contenedor corriendo en este momento se borra, aunque tenga tag y la hayas usado ayer. Si trabajas con varios proyectos y no arrancas todos los contenedores a diario, prune -a puede obligarte a re-descargar o re-construir imágenes que sí seguías necesitando.

`docker volume prune`: el que hay que usar con más cuidado

docker volume prune

Este comando borra todos los volúmenes que no están referenciados por ningún contenedor existente, exista o no ese contenedor en ejecución. Aquí está el matiz importante, y es precisamente donde está el riesgo real de encadenar los comandos de este artículo sin pensarlo: un contenedor parado (pero no borrado) sigue protegiendo su volumen — docker volume prune no lo tocaría todavía. El problema aparece cuando, justo antes, ejecutaste docker system prune, que sí borra los contenedores parados como parte de su limpieza. En el momento en que ese contenedor desaparece, su volumen queda huérfano — y un docker volume prune posterior sí lo borra, con los datos que contenía, de forma irreversible.

Es decir: el orden de limpieza que recomendamos más abajo (system prune → volume prune) es exactamente el que puede convertir un volumen “protegido por un contenedor parado” en un volumen huérfano y borrable en cuestión de dos comandos. Si tienes contenedores parados de proyectos en pausa con datos que todavía te importan, revisa esos contenedores antes de lanzar docker system prune, no solo antes del volume prune.

Antes de ejecutarlo, lista qué se va a borrar:

docker volume ls -f dangling=true

Revisa esa lista con calma. Si reconoces algún volumen de un proyecto que sigue vivo aunque el contenedor esté parado ahora mismo, no ejecutes el prune sin antes hacer un backup o arrancar ese contenedor para confirmar que no hay datos importantes.

# Backup rápido de un volumen antes de decidir si lo borras
docker run --rm -v nombre_del_volumen:/data -v $(pwd):/backup alpine \
  tar czf /backup/volumen-backup.tar.gz -C /data .

El combo que libera más espacio de golpe

Si has confirmado con docker system df que la mayoría del espacio reclamable está en imágenes y build cache (el escenario más habitual), este es el orden recomendado:

# 1. Limpieza segura: contenedores parados, redes huérfanas, caché de build
docker system prune

# 2. Si sigue faltando espacio, añade imágenes sin tag en uso (revisa antes)
docker image prune -a

# 3. Solo si has confirmado que no hay datos importantes, limpia volúmenes huérfanos
docker volume prune

Nota que separamos image prune -a de system prune -a — hacerlo en dos pasos te permite revisar docker system df entre medias y decidir si de verdad necesitas seguir liberando espacio antes de tocar volúmenes.

Configurar límites para que no vuelva a pasar

Más allá de la limpieza puntual, puedes evitar que Docker vuelva a llenarte el disco configurando un garbage collector automático en el propio demonio. Edita (o crea) /etc/docker/daemon.json:

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "10GB"
    }
  }
}

Esto le dice al demonio que mantenga la caché de build por debajo de 10GB automáticamente, purgando lo más antiguo cuando se supera ese umbral. Reinicia el servicio tras el cambio:

sudo systemctl restart docker

Si usas Docker Desktop en Windows/Mac con WSL2

Si trabajas con Docker Desktop sobre WSL2, hay una capa adicional a tener en cuenta: el espacio que libera docker system prune dentro del disco virtual de WSL2 (ext4.vhdx) no se refleja automáticamente como espacio libre en el disco de Windows — el fichero virtual no se reduce solo porque hayas borrado datos dentro de él. Tras una limpieza grande, si necesitas recuperar ese espacio también en el host de Windows, hace falta compactar el disco virtual manualmente:

wsl --shutdown
diskpart
# Dentro de diskpart:
select vdisk file="C:\Users\TuUsuario\AppData\Local\Docker\wsl\data\ext4.vhdx"
compact vdisk

Sin este paso adicional, puedes haber liberado correctamente el espacio “interno” de Docker (confirmado con docker system df) y aun así seguir viendo poco espacio libre en la unidad C: de Windows — es una fuente de confusión frecuente para quien no conoce este comportamiento de WSL2.

Verificación final

docker system df
df -h /var/lib/docker

Confirma que el espacio reclamado coincide aproximadamente con lo que esperabas liberar, y que df -h sobre la partición donde vive /var/lib/docker (normalmente / a menos que la hayas movido) ya tiene margen suficiente para tus próximos builds.

Resumen

Comando	Qué borra	Riesgo
`docker container prune`	Contenedores parados	Bajo
`docker image prune`	Imágenes dangling (sin tag)	Bajo
`docker image prune -a`	Todas las imágenes sin contenedor activo, aunque tengan tag	Medio-alto
`docker system prune`	Contenedores parados + redes + imágenes dangling + build cache	Bajo
`docker system prune -a`	Lo anterior + todas las imágenes con tag no usadas	Alto
`docker volume prune`	Volúmenes sin contenedor asociado, con datos	Alto — irreversible

Si solo recuerdas una regla de todo este artículo: nunca ejecutes docker volume prune sin listar antes qué volúmenes se van a borrar. Es, con diferencia, el comando de limpieza de Docker con más potencial de causar una pérdida de datos real.

Si además de espacio en disco te está dando problemas de permisos al ejecutar cualquiera de estos comandos, revisa “Got permission denied while trying to connect to the Docker daemon socket” en Ubuntu, donde cubrimos ese error específico.

Categorías: Desarrollo Docker

Etiquetas: docker espacio en disco devops