SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Docker prune: liberar espacio en disco en un VPS

Si el disco de tu VPS está lleno, identifica si lo ocupan imágenes, contenedores, caché o volúmenes y limpia solo lo necesario sin perder datos.

Busca qué está ocupando el espacio en disco antes de eliminar nada

Docker ocupa espacio en disco de un VPS en cuatro lugares: imágenes, contenedores detenidos, caché de compilación y volúmenes locales. Ejecuta primero docker system df para saber cuál contiene los datos, y después ejecuta el prune más específico que los elimine. El orden importa, porque el último comando de esta guía, docker volume prune -a, elimina datos y no se puede deshacer.

Empieza por el sistema de archivos, no por Docker.

df -h /
sudo du -xh --max-depth=1 /var/lib/docker | sort -h
sudo du -xh --max-depth=1 /var/lib/containerd | sort -h

df indica el nivel de ocupación. du muestra dónde se encuentra. La opción -x hace que du se limite a un solo sistema de archivos. Así no sigue un montaje hacia un volumen independiente ni cuenta los datos dos veces. Los directorios relevantes dependen del backend de almacenamiento. En una instalación nueva de Docker Engine 29.0 o posterior, el almacén de imágenes de containerd es el predeterminado. El contenido de las imágenes y las instantáneas de los contenedores se encuentran en /var/lib/containerd. Por eso aparece la segunda línea de du. Con cualquiera de los dos backends, hay dos directorios relevantes bajo /var/lib/docker: volumes contiene los datos de los volúmenes, y containers contiene los metadatos de los contenedores y los archivos de registro. Un host actualizado desde una versión anterior de Docker conserva la estructura clásica overlay2 hasta que la cambies. En esa estructura importan otros tres directorios: overlay2 contiene las capas de imágenes y contenedores, buildkit contiene la caché de compilación y image contiene los metadatos de las capas. docker info | grep -i driver-type muestra io.containerd.snapshotter.v1 en el almacén de imágenes de containerd y no muestra nada en overlay2. El almacén de imágenes de containerd conserva una copia comprimida y otra extraída de cada capa. Por eso las mismas imágenes ocupan más espacio en disco que con overlay2.

Conviene explicar sudo y los comodines del shell, porque causan muchos problemas. /var/lib/docker pertenece a root y tu usuario normal no puede leerlo, por lo que ls /var/lib/docker devuelve Permission denied. Un comando como sudo du -sh /var/lib/docker/* también falla, porque el shell expande * antes de que se ejecute sudo, y el shell no puede leer ese directorio. Por ese motivo, todos los comandos siguientes usan find o --max-depth en lugar de un comodín.

Ahora revisa la información que proporciona Docker.

docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          24        6         12.4GB    8.91GB (71%)
Containers      31        6         1.42GB    1.39GB (97%)
Local Volumes   14        5         6.03GB    4.11GB (68%)
Build Cache     212       0         9.87GB    9.87GB

Esas cifras proceden de una máquina concreta y no indican nada sobre la tuya. Interpreta la estructura de los datos. TOTAL cuenta los objetos, ACTIVE cuenta los que se están usando ahora y RECLAIMABLE es la estimación de Docker sobre lo que un prune podría liberar de esa fila.

Hay dos detalles de RECLAIMABLE que suelen causar confusión. Cuenta las capas de imagen compartidas una vez por cada imagen que las utiliza, por lo que la fila de imágenes normalmente indica más espacio del que realmente puedes liberar. Además, nunca incluye los archivos de registro de los contenedores, porque Docker no considera un archivo de registro un objeto recuperable. Cuando du muestra un directorio mucho mayor de lo que reconoce docker system df, la causa son los archivos de registro. Más abajo hay una sección sobre este caso.

Añade -v para obtener el desglose por objeto.

docker system df -v

Esto divide el resumen en una sección por cada tipo de objeto. La sección de imágenes añade las columnas SHARED SIZE y UNIQUE SIZE, para que puedas ver cuánto espacio ocupa realmente una imagen individual. La sección de volúmenes añade un recuento LINKS, que indica cuántos contenedores están conectados a ese volumen. Recuerda LINKS: un valor de 0 significa que ningún contenedor usa el volumen, y esa es la condición desde la que parte todo comando de prune de volúmenes.

Imágenes dangling frente a imágenes no utilizadas

Estas dos expresiones parecen intercambiables, pero no lo son. Los filtros se comportan de forma diferente porque se refieren a objetos distintos.

Una imagen dangling es una imagen sin etiqueta. Aparece como <none> en docker images. Se crea una en cada reconstrucción: docker build -t myapp:latest . mueve la etiqueta myapp:latest a la imagen nueva, y la imagen anterior conserva todas sus capas, pero pierde su nombre. Nada hace referencia a ella y ningún proceso la limpia automáticamente.

Una imagen no utilizada es cualquier imagen, tenga etiqueta o no, a la que ningún contenedor haga referencia actualmente. Una postgres:16 que descargó el mes pasado y a la que ningún contenedor hace referencia, esté en ejecución o detenido, no está utilizada, pero no es dangling.

docker image prune        # dangling images only
docker image prune -a     # every image no container refers to

El segundo comando pregunta primero.

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N]

Lea atentamente ese aviso. "Associated to them" significa un objeto de contenedor existente, esté en ejecución o detenido. Si ejecutó docker compose down, los contenedores han desaparecido, por lo que todas las imágenes utilizadas por esos servicios pasan a estar no utilizadas y -a las elimina todas. No se pierde nada que no pueda recuperar, pero el siguiente docker compose up -d vuelve a descargar o reconstruir todo, lo que consume ancho de banda y tiempo de compilación en un VPS pequeño. Esta es una razón práctica para saber qué elimina docker compose down y qué deja en ejecución stop antes de eliminar nada.

Un filtro excluye del alcance las imágenes recientes.

docker image prune -a --filter "until=240h"

Esto elimina las imágenes no utilizadas creadas hace más de 240 horas (10 días) y conserva las más recientes. El valor until acepta una cadena de duración de Go, como 240h, o una marca de tiempo absoluta, como 2026-08-01T00:00:00.

Qué es la caché de compilación y por qué crece tanto

BuildKit es el compilador que Docker usa de forma predeterminada para docker build y docker compose build desde Docker Engine 23.0. Almacena en caché el resultado de cada paso de cada Dockerfile que ejecuta. En el diseño clásico de overlay2, mantiene esa caché en /var/lib/docker/buildkit. La caché permite que la segunda compilación termine en segundos, por lo que cumple su función. Docker Engine ejecuta la recolección de basura de forma predeterminada. Elimina la caché que no se ha usado durante 60 días. El resto sólo se depura cuando supera los límites que Docker Engine calcula a partir del tamaño del disco. En un VPS pequeño, esto puede significar que el disco ya esté casi lleno. Compile la misma imagen cincuenta veces con un paso COPY que cambie cada vez. Hasta que se ejecute la recolección, conservará cincuenta conjuntos de capas.

La caché de compilación no aparece en docker image prune. Es un tipo de objeto independiente con su propio comando.

docker builder prune                        # dangling cache
docker builder prune -a                     # all unused cache
docker builder prune --filter until=168h    # cache untouched for 7 days

Ninguno de estos elementos afecta a sus imágenes ni a sus datos. El único coste de borrar la caché de compilación es que la siguiente compilación se ejecutará lentamente una vez. En un VPS que recompila imágenes con frecuencia, Build Cache suele ser la fila más grande de docker system df, por lo que es el elemento grande más seguro que puede eliminar.

Los comandos de limpieza, ordenados de menor a mayor riesgo

Siga esta lista y deténgase en cuanto df -h / vuelva a mostrar un estado normal. Cada comando muestra una línea Total reclaimed space: al terminar.

  1. docker container prune elimina los contenedores detenidos. También elimina sus capas de escritura, por lo que se borra todo lo que un contenedor haya escrito fuera de un volumen. Los volúmenes no se modifican.
  2. docker image prune elimina únicamente las imágenes huérfanas. Es el comando de imágenes más seguro.
  3. docker builder prune elimina la caché de compilación huérfana. El coste es una compilación lenta.
  4. docker image prune -a elimina todas las imágenes que no utiliza ningún contenedor. El coste es volver a descargarlas o compilarlas.
  5. docker system prune ejecuta los tres primeros pasos a la vez y añade las redes no utilizadas.
  6. docker volume prune elimina los volúmenes anónimos no utilizados.
  7. docker volume prune -a elimina los volúmenes no utilizados, incluidos los volúmenes con nombre. Este es el comando que elimina bases de datos.

docker system prune indica su propio alcance antes de ejecutarse.

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all dangling images
        - unused build cache
Are you sure you want to continue? [y/N]

Los volúmenes se excluyen deliberadamente de esa lista. Añadir --volumes incluye de nuevo los volúmenes anónimos. Añadir -a amplía el paso de imágenes, de las imágenes huérfanas a todas las imágenes no utilizadas. Ejecutar un docker system prune -a --volumes -f completo en un host de producción es una forma de perder datos al intentar liberar espacio.

Por qué la limpieza de volúmenes elimina la base de datos

Esta es la sección que debe leer dos veces.

Un volumen se considera no utilizado cuando ningún contenedor está asociado a él. Esa es toda la comprobación. Docker no verifica si el volumen está vacío, si un archivo compose todavía lo declara ni si contiene la única copia de la base de datos. LINKS 0 en docker system df -v significa no utilizado, y docker volume prune -a considera que todos los volúmenes no utilizados se pueden eliminar, salvo que un filtro label que haya añadido los excluya.

Ahora coloque dos acciones normales una detrás de otra. Ejecuta docker compose down para reiniciar una pila correctamente. Ese comando elimina los contenedores y deja los volúmenes con nombre en su sitio, que es exactamente lo que documenta. El volumen de Postgres ya no está asociado a ningún contenedor. Diez minutos después ejecuta docker volume prune -a para liberar espacio y la base de datos desaparece. Ambos comandos funcionaron correctamente. La secuencia destruyó los datos.

Desde Docker Engine 23.0 (versión de API 1.42), el comando sin opciones es más restrictivo que antes.

WARNING! This will remove anonymous local volumes not used by at least one container.

Un volumen anónimo es uno que Docker crea por usted, normalmente porque una imagen declara VOLUME y usted nunca le asignó un nombre. Normalmente contienen datos que no necesitaba conservar. Un volumen con nombre, como el que escribió en el archivo compose, sólo se elimina cuando añade -a. Las versiones anteriores de Docker eliminaban ambos tipos con el comando sin opciones, así que no confíe en hábitos adquiridos en un servidor que después haya actualizado. La diferencia sólo se entiende cuando sabe en qué se diferencian los volúmenes con nombre de los bind mounts, porque un bind mount no es un volumen de Docker y ningún comando prune lo tocará.

Compruebe antes de eliminar. Sustituya myapp_pgdata por el nombre del volumen que está comprobando.

docker volume ls -f dangling=true
docker volume inspect myapp_pgdata
sudo ls -la /var/lib/docker/volumes/myapp_pgdata/_data

El filtro dangling=true aplicado a un volumen significa sin referencias, no vacío. Mostrar _data le indica qué contiene realmente. Si encuentra dentro un directorio pgdata o mysql, deténgase y haga una copia antes de continuar. La misma destrucción puede producirse mediante docker compose down -v, que elimina los volúmenes con nombre declarados por el archivo compose, excepto los marcados con external, y no solicita confirmación.

Un volumen es el único elemento de un host Docker que una reconstrucción no puede recrear. Por eso los datos de los volúmenes deben incluirse en una copia de seguridad de restic que se ejecute fuera del servidor, donde un indicador escrito por error no pueda alcanzarlos.

Cuando no se libera espacio: los archivos de registro de los contenedores

Ha eliminado todo lo que se podía podar, docker system df muestra que casi no hay espacio recuperable y el disco sigue lleno. Revise los registros.

sudo find /var/lib/docker/containers -name '*-json.log' -exec du -h {} + | sort -h | tail -10

Cada contenedor escribe su salida estándar y su salida de error estándar en un archivo JSON bajo /var/lib/docker/containers/. En una instalación predeterminada, max-size no está definido, lo que significa que no hay límite. Por tanto, un solo contenedor atrapado en un bucle de fallos puede escribir hasta llenar la partición. Ningún comando de poda elimina estos archivos, porque los contenedores que los generan están en ejecución y, por definición, no se pueden podar.

No elimine el archivo. Ejecutar rm sobre un archivo de registro abierto no libera espacio, porque el daemon de Docker mantiene abierto un descriptor de archivo y el kernel conserva esos bloques asignados hasta que se cierre ese descriptor. df no cambiará en absoluto. En su lugar, trunque el archivo. Así se conserva el mismo inode y el daemon puede seguir escribiendo.

sudo find /var/lib/docker/containers -name '*-json.log' -exec truncate -s 0 {} +
df -h /

Es una solución temporal. docker logs para esos contenedores ya no devuelve nada y los archivos vuelven a crecer de inmediato. La solución real es configurar la rotación, que se explica en la sección siguiente.

Mida antes y después, siempre

No suponga lo que hizo un prune. Tome una medición, ejecute un comando y tome otra medición.

df -h /
docker system df
docker builder prune -f --filter until=168h
docker image prune -f
docker system df
df -h /

Compare las dos salidas de df. Ese es el único número que determina si el servidor sigue prestando servicio. docker system df indica qué fila cambió realmente, y cada prune muestra su propia cifra de Total reclaimed space:.

Si df no cambió, pero docker system df indica que se liberó espacio, un descriptor de archivo abierto mantiene los bloques eliminados. Ese es el problema del archivo de registro descrito arriba. Si ambos cambiaron y el disco vuelve a llenarse en un día, tiene un problema de crecimiento, no de limpieza. La solución es configurar la rotación y un trabajo programado.

Cómo evitar que el disco vuelva a llenarse

Limite el tamaño de los registros. Cree o edite /etc/docker/daemon.json.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Esto limita a 30 MB los registros de cada contenedor creado después del reinicio indicado más adelante. Todos los valores de log-opts deben ser cadenas, incluidos los valores numéricos. Compruebe que el archivo se pueda analizar antes de reiniciar, porque un daemon.json mal formado impide que el daemon se inicie y hace que todos los contenedores se detengan.

python3 -m json.tool /etc/docker/daemon.json
sudo systemctl restart docker
docker info | grep -i 'logging driver'

docker info ahora debería mostrar Logging Driver: json-file. Los límites aparecen en la sección LogConfig de docker inspect en un contenedor creado después del reinicio. Este es el detalle importante: esta configuración sólo se aplica a los contenedores nuevos. Los contenedores existentes conservan la configuración con la que se crearon, por lo que debe recrearlos.

docker compose up -d --force-recreate

También puede establecer el mismo límite por servicio en un archivo de compose. Esta es la mejor opción cuando un servicio genera demasiados registros y necesita un valor propio.

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Programe una limpieza selectiva. Ejecútela semanalmente y limítela a imágenes huérfanas y a la caché de compilación antigua. No incluya nunca -a ni --volumes en una tarea programada, porque una tarea que se ejecute mientras una stack está detenida eliminará las imágenes de esa stack y, con --volumes, empezará a actuar sobre sus datos.

sudo tee /etc/cron.weekly/docker-prune >/dev/null <<'EOF'
#!/bin/sh
docker image prune -f
docker builder prune -f --filter until=168h
EOF
sudo chmod +x /etc/cron.weekly/docker-prune
sudo /etc/cron.weekly/docker-prune

La última línea ejecuta el script una vez manualmente para que pueda ver su salida antes de que se ejecute sin supervisión. El archivo debe tener permisos de ejecución y su nombre no debe contener un punto, porque run-parts omite todo lo que no sea ejecutable y todo lo que tenga una extensión.

Alarme cuando quede poco espacio libre. Una limpieza que se ejecuta después de que el disco se llena es una recuperación. Una alerta al 80 por ciento es prevención.

usage=$(df --output=pcent / | tr -dc '0-9')
[ "$usage" -ge 80 ] && echo "root filesystem at ${usage} percent full"

Añádalo a cron con el notificador que ya utilice. El espacio libre sólo es una parte del problema, por lo que debe combinar la alerta con la supervisión del estado del disco en su VPS, porque un disco defectuoso y un disco lleno detienen los contenedores, pero requieren soluciones distintas.

Todo lo anterior presupone una instalación estándar con la raíz de datos en /var/lib/docker. Si la cambió mediante la clave data-root en daemon.json, sustituya la ruta en todos los comandos. En el almacén de imágenes de containerd, data-root no mueve los datos de imágenes y contenedores en /var/lib/containerd, porque esa ubicación la establece root en /etc/containerd/config.toml. Configurar correctamente este diseño en un servidor nuevo forma parte de configurar Docker en un VPS, y es mucho más fácil decidirlo antes de tener 40 GB de contenedores en la partición equivocada.

FAQ

¿docker system prune elimina mis volúmenes?

No. El comando básico elimina los contenedores detenidos, las redes no utilizadas, las imágenes huérfanas y la caché de compilación no utilizada. Su solicitud de confirmación enumera exactamente ese conjunto. Los volúmenes sólo se incluyen cuando añade --volumes. Desde Docker Engine 23.0, esa opción incluye los volúmenes anónimos, no los nominales. Los volúmenes nominales se eliminan con docker volume prune -a y docker compose down -v. Esos son los dos comandos que requieren especial cuidado.

¿Por qué el disco sigue lleno después de ejecutar docker prune?

Hay dos causas habituales. La primera son los archivos de registro de los contenedores en /var/lib/docker/containers/. Ningún comando prune los toca y crecen sin límite hasta que configura max-size. La segunda es un archivo eliminado que un proceso mantiene abierto. Si eliminó un registro con rm mientras su contenedor estaba en ejecución, el daemon conserva el descriptor de archivo y el kernel no libera los bloques. Por eso df no muestra ningún cambio. Compare sudo du -xh --max-depth=1 /var/lib/docker con docker system df para determinar cuál de las dos situaciones tiene.

¿Cuál es la diferencia entre docker image prune y docker image prune -a?

El comando básico elimina sólo las imágenes huérfanas, es decir, las imágenes que han perdido su etiqueta, casi siempre debido a una recompilación. La forma -a elimina todas las imágenes a las que ningún contenedor existente hace referencia, incluidas las imágenes etiquetadas que descargó deliberadamente. Después de ejecutar docker compose down, los contenedores han desaparecido, por lo que -a también eliminará las imágenes de esa pila. No se pierde nada de forma permanente, porque el siguiente inicio las vuelve a descargar o recompilar. Sin embargo, con una conexión lenta, la espera puede ser larga.

¿Cómo evito que los registros de Docker llenen el disco?

Configure max-size y max-file en log-opts dentro de /etc/docker/daemon.json. Después, reinicie el daemon con sudo systemctl restart docker. La configuración sólo se aplica a los contenedores creados después de ese reinicio. Por tanto, vuelva a crear los que estén en ejecución con docker compose up -d --force-recreate. Puede establecer las mismas dos opciones para cada servicio en un archivo compose, dentro de una clave logging. Esto es útil cuando un servicio genera muchos más registros que los demás.

¿Es seguro ejecutar docker system prune desde una tarea cron?

El comando docker system prune -f básico es seguro en un host donde todas las pilas permanecen en ejecución. Sin embargo, elimina los contenedores detenidos. Por tanto, eliminará un contenedor que haya detenido deliberadamente y que pensaba iniciar de nuevo más adelante. La tarea programada más segura es docker image prune -f junto con docker builder prune -f --filter until=168h. Libera los dos recursos que crecen más rápido y no puede tocar ningún volumen. Nunca programe -a ni --volumes.

¿Te resultó útil este artículo?