Docker sin espacio en disco: limpieza de imágenes, caché de compilación, registros y volúmenes

Si Docker se queda sin espacio, empieza por docker system df -v y después revisa los registros de los contenedores y los directorios montados. Prioriza la caché de compilación, las imágenes colgantes y los contenedores obsoletos que hayas confirmado que se pueden regenerar o descartar. Comprueba por separado a qué pertenecen los volúmenes y sus copias de seguridad: que un volumen figure como «sin uso» no significa que se pueda borrar.

Tras varios meses de autoalojamiento, pueden acumularse versiones de imágenes, caché de compilación, registros y datos de la aplicación. Un solo prune solo resuelve parte del problema; ampliar su alcance sin comprobarlo puede borrar una base de datos.

Esta guía se centra en Linux Docker Engine y Compose V2. Las consultas de Docker CLI suelen funcionar también en Windows PowerShell; los comandos del anfitrión marcados como Bash deben ejecutarse en la máquina Linux que realmente aloja Docker. La documentación se comprobó el 22 de octubre de 2026. No se han ejecutado operaciones de limpieza ni de recreación en tu servidor para elaborar este artículo.

Si llegas desde la guía para desplegar Syncthing con Docker o la de autoalojamiento de Joplin Server, localiza primero los directorios de datos que utilizan esos servicios antes de decidir qué limpiar.

Identifica el disco lleno y el anfitrión conectado

Docker CLI puede conectarse al equipo local, a un context SSH remoto o a la máquina virtual Linux de Docker Desktop. Si consultas el espacio en el context equivocado, las cifras pueden no corresponder al servidor que quieres revisar.

1
2
3
4
5

docker context show
docker context ls
docker version
docker info
docker compose version

Comprueba la información del servidor, el context actual y el directorio de datos de Docker. En Linux, el directorio predeterminado suele ser /var/lib/docker, pero las instalaciones rootless, las configuraciones personalizadas y otros backends de almacenamiento pueden utilizar rutas distintas. No trates esa ruta predeterminada como un directorio que debas borrar.

En el anfitrión Linux, comprueba la capacidad del sistema de archivos y los inodes:

1
2

df -h
df -i

Aunque quede capacidad libre, muchos archivos pequeños pueden agotar los inodes y provocar no space left on device. Si se escribe en un bind mount situado en otro disco, comprueba ese punto de montaje, no solo el disco del sistema.

Docker Desktop añade una capa de disco virtual. El espacio liberado dentro de los contenedores, la capacidad disponible del disco virtual y la ocupación real de su imagen en el anfitrión pueden cambiar en momentos distintos. Por tanto, que el uso de la unidad C: de Windows no disminuya inmediatamente no demuestra por sí solo que la limpieza haya fallado. Esta guía no proporciona un comando de compactación válido para todos los backends de Desktop.

Distingue cinco tipos de datos mediante el detalle de uso

Empieza con consultas de solo lectura:

1
2
3
4
5

docker system df
docker system df -v
docker ps -a --size
docker image ls
docker volume ls

docker system df muestra el uso de recursos de Docker; -v amplía el detalle de imágenes, contenedores y volúmenes locales. Las imágenes pueden compartir capas, por lo que sumar el SIZE de todas ellas no equivale al espacio real ocupado.

RECLAIMABLE estima el espacio que cumple las condiciones para recuperarse; no determina si la aplicación sigue necesitando esos recursos. Una imagen antigua puede ser la única versión útil para volver atrás, y un volumen sin referencias puede contener una base de datos retirada que aún deba conservarse.

El tamaño de la capa de escritura mostrado por docker ps --size tampoco equivale al total de datos montados y registros. Si ese valor es pequeño pero el uso del disco del anfitrión sigue aumentando rápidamente, investiga esas dos áreas a continuación.

Relaciona los contenedores con sus datos antes de limpiar

En los ejemplos, el contenedor se llama my-app; sustitúyelo por el nombre real:

1
2
3

docker inspect my-app --format '{{json .Mounts}}'
docker inspect my-app --format '{{json .HostConfig.LogConfig}}'
docker inspect my-app --format '{{.LogPath}}'

En Mounts, fíjate en estos campos:

• Type: distingue entre volume y bind.
• Name: nombre del volumen gestionado por Docker.
• Source: ruta de origen en el anfitrión.
• Destination: ubicación del montaje dentro del contenedor.
• RW: indica si el contenedor puede escribir.

Por ejemplo, si /data en el contenedor corresponde a /srv/my-app/data en el anfitrión, investiga su crecimiento desde el anfitrión y la aplicación. Borrar imágenes antiguas no reducirá la colección de adjuntos de ese directorio.

Si la base de datos aún se guarda en la capa de escritura del contenedor, prepara primero una copia de seguridad y la migración a almacenamiento persistente. Eliminar el contenedor en ese estado puede perder los datos, así que no continúes todavía con su limpieza.

En un proyecto Compose, ejecuta también estas consultas desde el directorio correcto:

1
2
3

docker compose config --quiet
docker compose ps -a
docker compose images

Si utilizas -f, -p o archivos de entorno personalizados, emplea los mismos parámetros en las consultas y en las operaciones posteriores. Cambiar el nombre del proyecto puede crear otro conjunto de volúmenes y hacer que la aplicación parezca vacía.

Anota los nombres reales de los volúmenes, los archivos Compose y las versiones de las imágenes. Guarda las copias en una ubicación independiente con capacidad suficiente. Utiliza copias lógicas o instantáneas coherentes admitidas por la base de datos; archivar directamente un directorio de base de datos en funcionamiento puede generar una copia imposible de restaurar.

Imágenes y caché: empieza por lo que se puede regenerar

Evalúa primero la caché de compilación

Si Build Cache ocupa la mayor parte del espacio, limpiarla suele ser más apropiado que tocar los volúmenes de la aplicación. La contrapartida es que la siguiente compilación puede necesitar descargar dependencias y compilar de nuevo, con un mayor tiempo de ejecución.

1

docker builder prune --filter 'until=168h'

Este comando elimina la caché elegible según un filtro de antigüedad y mantiene la confirmación interactiva. 168h equivale a siete días: es un ejemplo de retención que debes ajustar a la frecuencia de compilación. No es una vista previa; al confirmar, la caché se elimina realmente. Consulta los parámetros en docker builder prune.

Si utilizas Buildx con varios builders, comprueba también cuál está seleccionado:

1
2

docker buildx ls
docker buildx du

docker buildx du consulta el uso de caché del builder seleccionado. No observes un gran consumo en un builder y ejecutes repetidamente la limpieza en otro. Comprueba por separado las máquinas de compilación remotas; no supongas que comparten tu disco local.

Decide si puedes borrar las imágenes colgantes

Enumera las imágenes colgantes:

1

docker image ls --filter dangling=true

Después de confirmar que ya no necesitas esos artefactos, ejecuta:

1

docker image prune

De forma predeterminada, elimina imágenes colgantes. Añadir -a amplía el alcance a las imágenes que ningún contenedor referencia, incluidas versiones antiguas con etiquetas normales. Esto afecta a la recuperación sin conexión y a la vuelta a versiones anteriores; no lo utilices como opción rutinaria para acelerar la limpieza. Consulta las reglas completas en docker image prune.

Si solo quieres borrar una imagen que ya has confirmado como obsoleta, especificar su ID real facilita controlar el alcance:

1

docker image rm IMAGE_ID

Si aparece un conflicto de referencias, inspecciona los contenedores que la usan y reconsidera si debes conservarla. No añadas inmediatamente una opción de fuerza para ignorar el aviso.

Elimina los contenedores obsoletos de uno en uno por nombre

Que un contenedor esté detenido no significa que sus archivos carezcan de valor. Comprueba sus montajes y su capa de escritura antes de decidir si borrarlo:

1
2
3

docker ps -a --filter status=exited --size
docker inspect old-test-container --format '{{json .Mounts}}'
docker diff old-test-container

docker diff muestra cambios en el sistema de archivos del contenedor; no es una copia de seguridad ni sustituye la revisión de los directorios montados. Elimina el objeto concreto solo después de confirmar que es un contenedor de pruebas prescindible:

1

docker container rm old-test-container

Aquí no se utilizan -f ni -v. Aun así, eliminar el contenedor descarta su capa de escritura y sus registros; exporta primero los archivos importantes. Consulta las reglas en docker container rm.

Registros que no dejan de crecer: corrige la causa tras limpiar la caché

Si docker system df muestra poco espacio recuperable, revisa el controlador de registros y su ruta. El controlador predeterminado json-file no tiene un límite de tamaño por defecto, así que una salida frecuente de errores puede seguir consumiendo disco.

1
2
3
4

docker info --format '{{.LoggingDriver}}'
docker inspect my-app --format '{{json .HostConfig.LogConfig}}'
docker inspect my-app --format '{{.LogPath}}'
docker logs --tail 100 my-app

El controlador predeterminado puede ser distinto del que utiliza un contenedor; toma como referencia su LogConfig. LogPath tampoco siempre devuelve una ruta de archivo accesible directamente: depende del controlador y del entorno. Consulta el comportamiento en la documentación de controladores de registros de Docker.

En Linux, puedes consultar el tamaño de la ruta devuelta sin modificarla. Sustituye la ruta del ejemplo por la del archivo real:

1

sudo du -h /actual/path/to/container-json.log

No borres ni trunques directamente los archivos de registro gestionados por Docker. La documentación indica que los gestiona exclusivamente Docker daemon y que modificarlos externamente puede interferir con el sistema de registros. Si se repiten fallos de conexión a la base de datos o errores de permisos, corrige primero la aplicación; la rotación por sí sola no evita que se generen registros inútiles.

Configura la rotación de registros de un servicio Compose

Integra esta configuración logging en el servicio existente, conservando su imagen, puertos, variables de entorno y montajes de datos:

1
2
3
4
5
6
7

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

Es un fragmento de configuración, no un archivo Compose completo que puedas iniciar por separado. Sustituye app por el nombre real del servicio. max-size define el umbral de rotación de cada archivo y max-file la cantidad conservada; consulta los detalles en la documentación de json-file.

Comprueba la sintaxis tras editar. Recrea el servicio solo si puede interrumpirse brevemente y sus datos son persistentes y tienen copia de seguridad:

1
2
3

docker compose config --quiet
docker compose up -d --no-deps --force-recreate app
docker compose ps

La recreación sustituye el contenedor y no conserva automáticamente su capa de escritura. Si el servicio depende de volúmenes anónimos, determina antes cómo reutilizarlos o migrarlos. Después, localiza el nombre real del nuevo contenedor y compruébalo:

1
2

docker inspect my-app --format '{{json .HostConfig.LogConfig}}'
docker logs --tail 100 my-app

Editar la configuración y ejecutar docker compose restart no actualiza las opciones de registro fijadas al crear el contenedor. Si sigue apareciendo la configuración antigua, revisa el nombre del servicio, el archivo Compose, el nombre del proyecto y el ID real del contenedor.

La rotación limita el historial local; si necesitas auditorías a largo plazo, recoge y conserva los registros por separado. Los registros que la propia aplicación escribe en directorios montados también necesitan configuración o un mecanismo de rotación específico; la rotación de la salida estándar de Docker no gestiona esos archivos.

Volúmenes: sin uso no significa prescindible

Enumerar los volúmenes sin referencias de contenedores ayuda a localizar objetos que investigar:

1
2
3

docker volume ls --filter dangling=true
docker volume inspect my-project-data
docker ps -a --filter volume=my-project-data

Un volumen puede no tener un contenedor asociado simplemente porque se ejecutó docker compose down. Tras eliminar el contenedor, sus archivos de base de datos pueden seguir siendo todos los datos necesarios para el siguiente arranque. Consulta la persistencia en la documentación de Docker Volumes.

Antes de actuar, debes poder responder a cuatro preguntas:

1. ¿A qué aplicación y entorno pertenece este volumen?
2. ¿La aplicación se ha retirado definitivamente o se recreará más adelante?
3. ¿Existe una copia independiente y se ha verificado cómo restaurarla?
4. ¿Podría esta limpieza borrar también la ubicación de la copia?

Considera borrar un volumen concreto con docker volume rm 实际卷名 únicamente tras confirmar que ya no se necesita; sustituye el marcador final por el nombre real del volumen. Esta guía no plantea la limpieza masiva de volúmenes como mantenimiento rutinario. Si el crecimiento procede de registros de base de datos, adjuntos o modelos, utiliza primero las políticas de retención, el archivado o la migración admitidos por la aplicación.

El alcance de prune y compose down

No confundas los ámbitos de eliminación de los distintos comandos:

Comprueba el comportamiento exacto en --help de tu versión y en la documentación oficial vigente. Consulta system prune, volume prune y compose down.

Una limpieza masiva no se puede deshacer sin más. La caché se puede regenerar y quizá puedas descargar de nuevo las imágenes, pero recuperar volúmenes borrados requiere una copia válida. Además, que Compose no elimine por defecto los volúmenes anónimos no garantiza que el siguiente up vuelva a montar automáticamente el original. En servicios de larga duración, utiliza rutas explícitas o volúmenes con nombre y conserva su configuración.

Verifica tanto el espacio recuperado como las lecturas y escrituras

Revisa el uso después de tratar cada tipo de recurso para saber dónde se ha liberado espacio:

1
2
3
4

docker system df -v
docker ps -a --size
docker compose ps
docker compose logs --tail 100

Comprueba también el anfitrión Linux:

1
2

df -h
df -i

Que un contenedor muestre Up no basta para dar la recuperación por terminada. Abre el servicio, lee un registro existente, escribe uno de prueba que puedas borrar y confirma que la base de datos o el directorio de sincronización utilizan los datos originales. En servicios recreados para cambiar los registros, observa el crecimiento del disco durante un tiempo para confirmar que la rotación está configurada y los errores de la aplicación se han resuelto.

Si se ha liberado mucho menos de lo esperado, investiga según el síntoma:

En el último caso, detén inmediatamente las nuevas escrituras y comprueba si sigue existiendo el volumen antiguo o si la configuración apunta a un directorio nuevo. No continúes con la limpieza de volúmenes: podrías borrar definitivamente datos antiguos que todavía se pueden recuperar.

Si el servicio falla después de limpiar, restaura la configuración Compose, revisa los montajes persistentes y recréalo con una versión de imagen conservada. Si se borró el volumen, descargar de nuevo la imagen no recuperará los datos; sigue el procedimiento de restauración de copias que hayas verificado previamente.

Planifica el mantenimiento posterior

Registra como mínimo el context de Docker, el uso de recursos, los directorios de datos reales, el controlador de registros y la ubicación de las copias. En equipos de desarrollo que compilan con frecuencia puedes evaluar periódicamente la caché; en servidores con bases de datos de larga duración, prioriza las alertas de capacidad, las copias de seguridad y los ensayos de restauración.

No programes directamente comandos que incluyan opciones de fuerza, limpieza amplia de imágenes y eliminación de volúmenes. Recoge primero estadísticas de solo lectura durante un tiempo, identifica qué recursos crecen de forma sostenida y elige la política de retención correspondiente.

Para trasladar datos a otro disco, consulta transferencia incremental y verificación con rsync. En directorios de bases de datos debes detener las escrituras relacionadas o utilizar una copia coherente admitida por la aplicación; copiar archivos correctamente no demuestra que la base de datos se pueda restaurar.