Limpieza de Overlay2 de Docker: Recupera Espacio en Disco con Seguridad (2026)

La limpieza de overlay2 de Docker es lo que necesitas cuando /var/lib/docker/overlay2 se come el disco y Docker empieza a fallar en las escrituras. Esta guía muestra cómo recuperar espacio en disco de forma segura: la familia docker system prune, límites de logs de contenedores, y un checkpoint del backend de almacenamiento que no deberías saltarte. Desde Docker Engine 29, las instalaciones nuevas guardan las imágenes en /var/lib/containerd, así que puede que el directorio que llena tu disco ni siquiera sea overlay2. Abajo está el camino completo: identifica el backend, mide, poda, arregla los logs, diagnostica restos, previene que vuelva a crecer.

Paso 0: ¿Qué backend de almacenamiento? (overlay2 vs store de imágenes containerd)

Antes de cualquier limpieza, averigua dónde guarda Docker sus datos realmente. Es una comprobación de solo lectura:

docker info -f '{{ .DriverStatus }}'

Dos resultados posibles:

• La salida contiene [[driver-type io.containerd.snapshotter.v1]] → estás en el store de imágenes containerd. Tus datos viven bajo /var/lib/containerd.
• La salida muestra un estado de driver overlay2 normal → estás en el store overlay2 heredado. Tus datos viven bajo /var/lib/docker/overlay2.

Flujo de decisión de limpieza overlay2 de Docker: ejecuta el comando docker info driver status, luego bifurca al store de imágenes containerd o al store overlay2 heredado y vigila el directorio correspondiente

Si estás a punto de montar una máquina nueva y quieres los defaults actuales documentados de principio a fin, instala Docker y Docker Compose en Ubuntu ARM primero, luego vuelve aquí.

# what to watch
du -sh /var/lib/docker/overlay2

# what Docker reports
docker system df

# what to watch
du -sh /var/lib/containerd

# what Docker reports (still authoritative)
docker system df

Verifica: pega la salida real de docker info -f '{{ .DriverStatus }}' en tus notas antes de podar. Quieres una línea base de qué store está activo.

Modo de fallo: “Podé overlay2 y no se recuperó nada.” En un host con store containerd estabas mirando el store inactivo. Los comandos de poda del store activo no tocan los datos del otro backend (mira la sección del store oculto más abajo).

Contexto de versiones, corto: el mundo viejo se ha ido. AuFS y el driver overlay heredado se eliminaron en Engine v24, devicemapper en v25, los plugins de graphdriver en v28 (consejo oficial de reemplazo: usa el store de imágenes containerd). Engine v29 requiere API v1.44 o más nueva. Si tus notas de limpieza son anteriores a 2023, reléelas antes de ejecutar nada.

Qué hay dentro de /var/lib/docker/overlay2

overlay2 es el filesystem copy-on-write de Docker para Linux. El directorio contiene:

• Directorios de capas: carpetas direccionadas por contenido con los diffs reales del filesystem
• Datos “upperdir” de contenedores: las capas escribibles donde los contenedores escriben archivos. Esto es normalmente lo que crece
• Metadatos y enlaces: estructuras que Docker usa para rastrear qué capas pertenecen a qué imágenes

Los nombres de las carpetas son hashes aleatorios, no identificadores legibles. No puedes mirar el nombre de una carpeta y saber a qué imagen pertenece. Usa comandos Docker en vez de adivinar por nombres de directorio. Docker mantiene este layout deliberadamente sin documentar.

En hosts con store containerd los internos equivalentes viven bajo /var/lib/containerd como un content store más snapshots overlayfs. Misma regla: mide con comandos Docker y du, no navegando carpetas hash.

Diagrama de dónde vive realmente el espacio en disco de Docker: capas overlay2 y capas escribibles, logs json de contenedores, volúmenes, caché de BuildKit bajo /var/lib/docker, más blobs y snapshots bajo /var/lib/containerd

Ese mapa vale la pena tenerlo en la cabeza. El resto de esta guía recorre cada caja: mídela, límpiala, y luego evita que vuelva.

Por qué /var/lib/docker/overlay2 crece tanto

El directorio crece por un puñado de razones predecibles:

1. Imágenes y contenedores sin usar: los contenedores parados y las imágenes viejas siguen ocupando espacio si no los eliminas.
2. Caché de build: Docker cachea capas para hacer los builds más rápidos. En una máquina que construye a menudo, esta caché es el principal culpable.
3. Imágenes y contenedores grandes: algunas imágenes traen binarios o archivos de datos grandes. Cuatro copias de una imagen base de 1,5 GB suman.
4. Capas de imagen ineficientes: imágenes con demasiadas capas o basura de build sobrante desperdician espacio. Si controlas el Dockerfile, copia múltiples archivos en una capa con un Docker COPY en vez de apilar un COPY por archivo.
5. Logs de contenedores sin límite: este es el escurridizo. El driver de logs json-file crece sin límite por defecto, y los archivos no están en overlay2. Viven en /var/lib/docker/containers/. Hay una sección dedicada abajo.

En hosts con store containerd, añade una más: los blobs más los snapshots desempaquetados hacen que el mismo conjunto de imágenes cueste más disco que el store heredado.

Si quieres ver qué categoría crece realmente con el tiempo, monitoriza recursos del servidor y Docker (CPU, memoria, disco) en vez de correr du a mano cada semana.

Nota de ops: un filesystem lleno no solo rompe los pulls de Docker. Los contenedores de bases de datos también pierden escrituras, y algunos de esos fallos son silenciosos hasta que la app da error. Apunta a un 15-20% de espacio libre en cualquier host que corra contenedores con estado.

Comprueba primero el uso de disco de Docker

Haz esto antes de tocar nada. Es de solo lectura.

docker system df
docker system df -v

docker system df muestra el uso de espacio para imágenes, contenedores, volúmenes y caché de build. El flag -v añade detalle por objeto. Para scripts de monitorización, añade --format json (o una plantilla Go) para parsear en vez de raspar tablas.

Luego comprueba el filesystem real:

df -h /var/lib/docker
du -sh /var/lib/docker/overlay2 /var/lib/docker/containers /var/lib/containerd 2>/dev/null

Para ver qué subdirectorios de overlay2 son los más grandes, solo para investigación, nunca para borrado:

du -sh /var/lib/docker/overlay2/* 2>/dev/null | sort -hr | head -10

Cómo leer la salida:

• Un uso grande de overlay2 suele significar escrituras de contenedores o caché de build, no solo imágenes sin usar.
• Céntrate en la categoría que crece en docker system df -v (imágenes, contenedores, volúmenes, caché de build), no en IDs específicos.
• Guarda la salida de docker system df -v antes de limpiar. Esa es tu línea base; compararás contra ella después.

Síntoma → causa probable → primer comando

Limpieza de Overlay2 de Docker: el playbook de poda

Esta es la limpieza ordenada, de más segura primero. Cada comando dice qué elimina. Ejecuta uno, comprueba docker system df, luego decide si necesitas el siguiente. Es más lento que lanzarlo todo a la vez y mucho más fácil de explicar cuando desaparece algo que querías.

Victoria rápida: docker system prune (y -a)

Empieza con el informe de solo lectura otra vez para tener números frescos:

docker system df -v

Elimina contenedores parados, redes sin usar, imágenes colgantes y caché de build:

docker system prune -f

Qué hace: limpia objetos que nada referencia. Qué no hace: tocar volúmenes nombrados, y mantiene imágenes a las que algún contenedor (incluso parado) todavía apunta.

Si también quieres eliminar todas las imágenes no usadas por ningún contenedor, que es el paso más agresivo:

docker system prune -a -f

Modo de fallo: -a elimina imágenes que un contenedor parado-pero-deseado necesita en su próximo arranque. Nada se corrompe, pero pagas el tiempo de re-pull en el peor momento. En hosts con contenedores que guardas para rollback, sáltate -a o córrelo dentro de una ventana de mantenimiento.

Para mantenimiento programado en máquinas de build, los filtros mantienen la poda honesta:

docker system prune -af --filter until=168h

until= acepta timestamps RFC3339, fechas, o duraciones Go como 10m y 24h. label= selecciona por etiqueta. Múltiples filtros entre claves distintas se combinan con AND. Un cron semanal con until=168h es un default aburrido y fiable para runners de CI.

Si quieres el playbook de demolición completo para imágenes, volúmenes, redes y discos, mira cómo limpiar todas las imágenes Docker con discos y todo.

Verifica: docker system df tras cada comando. En hosts con store containerd, ten en cuenta que builds viejos de Engine 29 sub-reportaban el espacio recuperado porque ignoraban los datos de imagen desempaquetados (moby#52905, corregido en un patch posterior de v29). Los números confusos ahí eran un bug, no un error tuyo.

Volúmenes: anónimos vs nombrados (docker volume prune -a)

Esta es la parte que las guías viejas hacen mal, y es por lo que la gente busca “docker volume prune no recupera espacio”.

Desde Docker Engine 23.0 / API 1.42, docker volume prune elimina solo volúmenes anónimos. Los volúmenes nombrados necesitan el flag -a:

docker volume prune -f        # anonymous volumes only
docker volume prune -a -f     # ALSO unused named volumes, check first!

Misma advertencia para docker system prune --volumes: el aviso oficial dice que elimina “todos los volúmenes anónimos no usados por al menos un contenedor”. Los volúmenes nombrados sobreviven.

Comprueba antes de borrar nada:

docker volume ls
docker system df -v

Verifica: docker volume ls antes, docker system df después. Si la fila de volúmenes apenas se movió tras docker volume prune -f, es esperado: tu espacio está en volúmenes nombrados, y solo -a los recuperará.

Caché de build: docker builder prune con topes de capacidad

Si construyes imágenes en el host, la caché de BuildKit es a menudo la categoría individual más grande. Pódala directamente:

docker builder prune -f       # dangling cache
docker builder prune -af      # all unused cache

El buildx más nuevo (v0.38.0 a 10-2026) añade topes de capacidad, que son mejores que esperar a las alarmas de disco lleno:

docker builder prune -f --max-used-space 10gb    # LRU-evict down to 10 GB
docker builder prune -f --min-free-space 20gb    # keep 20 GB free on the filesystem
docker builder prune -f --reserved-space 5gb     # never evict the last 5 GB of cache
docker builder prune -f --filter until=168h      # cache older than 7 days
docker buildx prune -a --max-used-space 10gb     # also internal/frontend images

Los tamaños son legibles y no distinguen mayúsculas (10gb, 500MB). Los filtros incluyen type=, type!=exec.cachemount (mantén cache mounts, normalmente lo que quieres), until=, description=, y parent=. Múltiples flags --filter se combinan con AND.

Si self-hosteas CI, self-hostea tu Git y CI/CD con Forgejo y Woodpecker CI y pon la poda --max-used-space en un timer semanal en el runner. Ahí es donde la caché de build se vuelve salvaje.

Modo de fallo: unknown flag: --keep-storage. Los tutoriales viejos lo usan; la tabla actual de opciones de buildx prune no lo lista. Ejecuta docker builder prune --help en tu host y usa el flag de capacidad que tu versión tenga realmente (--max-used-space en buildx reciente). No recuperar nada en una máquina fresca es normal, no un bug.

Verifica:

docker builder prune --help | grep -E 'max-used|keep-storage'

Luego re-ejecuta docker system df y compara la fila de Build Cache contra tu línea base.

El verdadero asesino de disco: los logs de contenedores Docker

Los logs de contenedores son el problema de disco que ninguna limpieza de overlay2 arreglará. El driver de logs json-file por defecto escribe en /var/lib/docker/containers/<id>/<id>-json.log y crece sin límite (max-size va por defecto a -1, max-file a 1). Una app habladora en un VPS pequeño puede llenar el disco en días mientras docker system df parece casi limpio.

Encuentra a los culpables:

du -sh /var/lib/docker/containers/* 2>/dev/null | sort -hr | head
docker ps -s

docker ps -s muestra el tamaño de la capa escribible de cada contenedor, lo que te dice si el bulto son logs o escrituras de la app.

truncate -s 0 /var/lib/docker/containers/*/*-json.log

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

sudo systemctl restart docker

Si prefieres enviar los logs a un sitio central en vez de rotarlos localmente, redirige los logs de Docker a un único archivo con un driver de logs distinto.

Verifica:

du -sh /var/lib/docker/containers
docker inspect <container> --format '{{ json .HostConfig.LogConfig }}'

Un contenedor nuevo debería mostrar "max-size":"10m" y "max-file":"3".

Modo de fallo: editaste daemon.json, reiniciaste Docker, y los logs siguen creciendo. Los contenedores viejos nunca fueron recreados. Comprueba docker inspect en uno de ellos; si la config de logs sigue vacía, el archivo no se re-leyó para ese contenedor.

Mapear directorios overlay2 a objetos Docker

A veces necesitas saber qué contenedor posee una capa escribible gigante. Usa la propia salida de Docker antes de cualquier scripting:

docker ps -s
docker inspect -f '{{ .Name }} {{ .GraphDriver.Data.UpperDir }}' $(docker ps -aq)

GraphDriver.Data.UpperDir es la ruta de la capa escribible directamente de docker inspect. Es un mapeo soportado, y la forma más rápida de casar un directorio enorme con un nombre de contenedor.

Para imágenes versus directorios de capas, tengo un script auxiliar que visualiza el uso de disco de overlay2:

curl -sSL https://utils.bitdoze.com/scripts/docker-overlay2-view.sh | bash

Todos los scripts están en utils.bitdoze.com.

Por qué los subdirectorios overlay2 no coinciden con los IDs de imagen

Podaste todo y todavía hay directorios hash que no coinciden con ninguna imagen. Normal. He aquí por qué:

1. Capas escribibles de contenedores: los contenedores corriendo o parados tienen cada uno una capa escribible en overlay2. Si tienes contenedores, tienes datos overlay.
2. Caché de build: los builds modernos (BuildKit) crean datos de caché. docker system prune -a no siempre lo elimina todo. Apúntale con docker builder prune.
3. Capas compartidas o referenciadas: las imágenes comparten capas, y Docker no eliminará nada aún referenciado. El nombre del directorio no coincidirá con lo que ves en docker image ls.
4. Capas init y metadatos internos: los directorios *-init y las estructuras de metadatos son parte de cómo Docker prepara los contenedores.
5. Datos filtrados u huérfanos (raro): cortes de luz, crashes del daemon o corrupción de almacenamiento pueden dejar restos. Comprueba docker system df -v y los logs del daemon antes de asumir que es tu caso.
6. Store heredado oculto tras un cambio de backend: este es nuevo. Si te moviste al store de imágenes containerd (o al revés), los datos del store inactivo se quedan en disco pero son invisibles para los comandos de poda del store activo. La poda no reporta nada que recuperar mientras df muestra un disco lleno. Detéctalo con docker info -f '{{ .DriverStatus }}' y compara contra du -sh /var/lib/docker/overlay2 /var/lib/containerd.

Incluso si un directorio parece sin usar, borrar directorios overlay2 a mano puede corromper el estado de Docker. Si de verdad necesitas un comienzo fresco, haz el reset controlado de abajo con Docker parado y tus datos respaldados.

Evita que /var/lib/docker/overlay2 vuelva a llenarse

La limpieza es una victoria única. Estos cinco hábitos mantienen el disco sano:

1. Pon tope al tamaño de logs. Los log-opts de daemon.json de la sección de logs son el cambio de mayor palanca en cualquier host que corra contenedores habladores.
2. Programa mantenimiento en máquinas de build. Un timer semanal gana a una alarma de disco lleno:

docker system prune -af --filter until=168h
docker builder prune -af --max-used-space 10gb

3. Mueve el data dir de Docker a un volumen más grande. Los discos raíz pequeños son la razón habitual por la que Docker llena la partición del SO. En /etc/docker/daemon.json:

{
  "data-root": "/mnt/volume/docker"
}

El flag también es --data-root en la línea de comandos de dockerd (los viejos flags -g/--graph se eliminaron en Engine v23). Si la máquina necesita el hardware, añade un nuevo disco a Ubuntu LVM y móntalo permanentemente primero. En máquinas VPS estilo Hetzner donde el disco raíz es pequeño y un volumen separado es barato, los planes cloud optimizados en coste de Hetzner combinan bien con este montaje, y un Hetzner Cloud VPS con un volumen montado resuelve el problema de “Docker se comió el disco del SO” sin mover datos después. Un VPS de Hostinger con almacenamiento NVMe es la alternativa si quieres un único disco local grande en su lugar. El margen de almacenamiento es más barato que el downtime.

Aviso: data-root no migra datos existentes. Planea una copia o movimiento con el daemon parado, luego verifica con docker info | grep 'Docker Root Dir' antes de borrar nada de la ruta vieja.

4. Alerta sobre uso de filesystem. Mantén un 15-20% libre y que te pagen antes del 80%, no después de que fallen las escrituras. Monta Beszel y Uptime Kuma para monitorización de servidor y alertas de disco si quieres una ruta self-hosted.
5. Mantente parcheado. Los patches de Engine 29.x han incluido tanto la corrección de sub-reporte de poda como una corrección de envenenamiento de caché de BuildKit (GHSA-p3rc-w3hc-pqvv, febrero de 2026): una imagen de caché maliciosa o caché remota puede inyectar caché de build falsa en tus builds. Esa golpea a cualquiera que importe caché de build, no solo a usuarios del store containerd. Las correcciones de seguridad aterrizan en releases de patch; ejecútalas.

Verifica tras cualquier cambio de data-root:

systemctl status docker
docker info | grep 'Docker Root Dir'

Modo de fallo: una errata en daemon.json (un número donde se requiere un string, una coma que falta) impide que dockerd arranque. journalctl -u docker muestra el error de parseo. Guarda una copia del último archivo que funcionaba antes de editar.

Último recurso: reset controlado de Docker (ambos stores)

Verifica: df -h antes y después, docker info muestra un root dir fresco, y un contenedor de prueba arranca (docker run --rm alpine echo ok). Solo entonces programa la limpieza de .bak.

FAQ: preguntas sobre limpieza de overlay2 de Docker

Resumen

Un /var/lib/docker/overlay2 que crece (o /var/lib/containerd en hosts Engine 29) se reduce a cuatro cosas: objetos sin usar, caché de build, escrituras de capas escribibles, y logs de contenedores sin límite. Haz la limpieza de overlay2 de Docker en ese orden de culpables: corre docker system df -v, poda con los comandos soportados (recuerda que los volúmenes nombrados necesitan docker volume prune -a), pon tope a tus logs con log-opts, y programa mantenimiento en vez de esperar a la alarma de disco lleno.

No borres nada dentro de esos directorios a mano. Si llegas al punto en que la poda ya no tiene nada que dar y el disco sigue lleno, haz el reset controlado con el daemon parado y los backups en su sitio.