Cómo solucionar el error «No hay espacio disponible en el dispositivo» de Docker: Una guía completa

El error de Docker «no hay espacio disponible en el dispositivo» suele aparecer en el peor momento posible: en mitad de una implementación, durante una compilación crítica o al extraer una imagen esencial. A veces me he encontrado con este error, y puedo decirte que apresurarse a eliminar archivos sin un diagnóstico adecuado es una receta segura para la pérdida de datos.

Lo que hace que este error sea especialmente difícil de solucionar es que rara vez tiene una única causa. Es posible que estés lidiando con imágenes Docker acumuladas, registros de contenedores descontrolados, inodos agotados por millones de archivos pequeños o incluso espacio «fantasma» consumido por archivos eliminados que aún permanecen abiertos por procesos en ejecución. Cada situación requiere una solución diferente.

Por eso siempre insisto en que hay que diagnosticar antes de actuar. Comprender la causa raíz te permite aplicar soluciones específicas de manera eficiente y evitar interrumpir tu entorno de producción. En esta guía, te explicaré un método sistemático para diagnosticar, resolver y prevenir este frustrante problema.

Si eres nuevo en Docker, te recomiendo que realices nuestro curso práctico Introducción a Docker , que cubre todo lo que necesitas para empezar con la contenedorización.

¿Qué es el error «No hay espacio disponible en el dispositivo» de Docker?

Cuando Docker muestra este error, está indicando uno de dos problemas fundamentales con el almacenamiento de tu sistema:

• Agotamiento de bloques del disco físico
• Agotamiento de inodos

Comprender la diferencia entre estas causas es fundamental para aplicar la solución adecuada.

Causas fundamentales del error «No hay espacio disponible en el dispositivo»

La primera causa y la más evidente es el agotamiento de los bloques del disco físico. Tu sistema de archivos se ha quedado sin espacio de almacenamiento real para escribir datos. Este es el escenario más intuitivo: simplemente has llenado tu disco con imágenes de Docker, contenedores, registros u otros archivos.

La segunda causa, menos obvia, es el agotamiento de los inodos. Incluso con gigabytes de espacio libre disponible, tu sistema de archivos puede quedarse sin inodos (estructuras de metadatos utilizadas para rastrear archivos y directorios). Cada archivo y directorio consume un inodo, por lo que las aplicaciones que crean millones de archivos pequeños (como los archivos de sesión PHP o los directorios « node_modules » de npm) pueden agotar los inodos y dejar espacio en disco sin utilizar.

Comprender el controlador de almacenamiento overlay2

Docker suele utilizar el controlador de almacenamiento overlay2, basado en Linux OverlayFS. OverlayFS superpone múltiples directorios en un único host y los presenta como un sistema de archivos unificado. Las capas de imagen se montan como directorios inferiores de solo lectura, mientras que cada contenedor en ejecución añade una capa superior delgada en la que se puede escribir. La vista combinada se muestra como un único directorio para el contenedor.

El controlador overlay2 admite de forma nativa hasta 128 capas OverlayFS inferiores en teoría, pero el almacén de capas de Docker impone un límite práctico de 125 capas base por imagen. Permite una composición eficiente de imágenes y un rendimiento mejorado para operaciones como docker build y docker commit. 

Aunque overlay2 está diseñado para consumir menos inodos que los controladores de almacenamiento anteriores, los entornos Docker que crean imágenes, extraen capas o crean contenedores de forma repetida pueden seguir ejerciendo una presión significativa sobre los bloques de disco y los inodos con el tiempo, especialmente cuando las imágenes o las capas de aplicaciones contienen muchos archivos pequeños.

La forma en que aparece este error depende del entorno de implementación:

• En sistemas Linux nativos, afecta al sistema de archivos que respalda /var/lib/docker. 

• En Docker Desktop para Windows o macOS, la limitación existe dentro de la imagen de disco de la máquina virtual de Docker (como un archivo .raw o .vhdx ), lo que introduce consideraciones adicionales a la hora de recuperar o cambiar el tamaño del almacenamiento.

Paso 1: Diagnosticar la causa raíz

Antes de eliminar nada, siempre empiezo por realizar un diagnóstico exhaustivo. Esta inversión de unos pocos minutos puede ahorrarte horas de resolución de problemas y evitar la pérdida accidental de datos.

Comprueba la capacidad a nivel del sistema.

Comienza por examinar el uso del disco de tu sistema host con df -H (df significa «disk free», disco libre):

df -H

Comprobación gratuita del disco en WSL

Este comando muestra el uso del disco en un formato legible para los usuarios. Busca sistemas de archivos que estén al 100 % de su capacidad o cerca de ella. 

En instalaciones nativas de Linux, presta especial atención a la partición donde reside /var/lib/docker. Normalmente se trata de la partición raíz (/) o de una partición Docker dedicada. 

En Docker Desktop (Windows/Mac), busca el montaje del sistema de archivos principal (normalmente /dev/sdf o similar), que contiene los datos de la máquina virtual Docker, en lugar de referencias específicas a /var/lib/docker, ya que Docker se ejecuta dentro de una máquina virtual.

A continuación, comprueba si se han agotado los inodos utilizando df -i:

df -i

Comprobación de agotamiento de inodos

Si observas un uso del 100 % de los inodos (IUse%) en cualquier sistema de archivos, habrás encontrado el problema. Este escenario es sorprendentemente común en servidores de compilación y entornos CI/CD, donde Docker crea y destruye repetidamente contenedores con muchos archivos pequeños.

Analizar el uso específico de Docker

Ahora que hemos determinado si el problema es el espacio en disco o los inodos, profundicemos y examinemos el consumo específico de recursos de Docker. El comando ` docker system df ` proporciona un resumen de alto nivel que funciona de forma universal en todas las instalaciones de Docker:

docker system df

Este resultado divide el uso del espacio en cuatro categorías: Imágenes, contenedores, volúmenes locales y caché de compilación.

La columna « RECLAIMABLE » (El mundo de los libros) es especialmente valiosa. Muestra cuánto espacio puedes recuperar sin afectar a los contenedores en ejecución. Es fundamental comprender la diferencia entre estas dos métricas: el espacio «activo» está actualmente en uso por contenedores en ejecución, mientras que el espacio «recuperable» se puede liberar de forma segura.

Para obtener detalles más precisos, añade la bandera verbose:

docker system df -v

Análisis del uso de Docker

Esta salida detallada enumera cada imagen, contenedor y volumen individualmente con sus tamaños, proporcionando el desglose detallado que necesitas para identificar los elementos que ocupan más espacio. Esto es lo que debes buscar en cada sección:

• Imágenes: Muestra el tamaño de cada imagen y si está actualmente en uso. Busca imágenes grandes que no se utilicen o que estén duplicadas con etiquetas diferentes. Las imágenes marcadas como «sin usar» se pueden eliminar de forma segura sin afectar a los contenedores en ejecución.

• Contenedores: Muestra el tamaño de la capa grabable para cada contenedor. Si un contenedor detenido muestra un SIZE significativo aquí, significa que ha estado escribiendo datos en su sistema de archivos. La columna « CREATED » ayuda a identificar contenedores antiguos que podrían haber sido olvidados.

• Volúmenes: Enumera los tamaños de los volúmenes y si están en uso. Los volúmenes marcados como no utilizados son candidatos seguros para su eliminación, aunque siempre hay que verificar que no contengan datos importantes antes de eliminarlos.

• Crear caché: A menudo el mayor consumidor y con frecuencia pasado por alto. Son capas intermedias de operaciones docker build que Docker conserva para acelerar las compilaciones posteriores.

Comandos específicos del sistema operativo

Los usuarios nativos de Linux que deseen obtener información aún más detallada sobre el sistema de archivos pueden examinar directamente los subdirectorios para ver cuáles (overlay2, containers, volumes) consumen más espacio:

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

Sin embargo, para los usuarios de Docker Desktop, /var/lib/docker se encuentra dentro de la máquina virtual oculta de Docker y no es directamente accesible. La buena noticia es que docker system df -v proporciona toda la información útil que necesitas, independientemente de tu plataforma, lo que lo convierte en el método de diagnóstico más fiable.

Paso 2: Limpiar el sistema con Docker Prune 

Después de identificar dónde se consume el espacio, puedo recuperarlo de forma segura utilizando los comandos de poda integrados en Docker. Estas operaciones están diseñadas para eliminar solo los recursos no utilizados, minimizando el riesgo de interrumpir los servicios en ejecución.

Elimina los recursos sobrantes.

Docker distingue entre recursos «colgantes» y «sin usar». Una imagen colgante es aquella que no tiene etiqueta ni referencias de contenedor. Normalmente, una capa intermedia de una compilación que ha fallado o ha sido sustituida. Siempre se pueden quitar sin peligro.

Comienza con el comando básico prune:

docker system prune

Esto elimina todos los contenedores, redes e imágenes colgantes que no se utilizan. No afectará a las imágenes o volúmenes etiquetados, a menos que se especifique explícitamente. Docker te pedirá confirmación antes de continuar.

Para ser más agresivo y eliminar todas las imágenes no utilizadas (no solo las que están colgando), añade el indicador --all:

docker system prune --all

Poda del sistema Docker

Este comando elimina cualquier imagen que no esté asociada actualmente a un contenedor. Ten cuidado: las implementaciones posteriores tendrán que volver a extraer las imágenes eliminadas.

Si deseas incluir volúmenes en la limpieza (que contienen datos persistentes), añade el indicador --volumes:

docker system prune --all --volumes

Advertencia: Esto elimina permanentemente los datos de los volúmenes no utilizados. Siempre verifica que los volúmenes no contengan datos importantes antes de utilizar esta bandera.

Gestionar la caché de compilación

Aquí es donde las cosas se ponen interesantes. La caché de compilación, que almacena capas intermedias de las operaciones de compilación de Docker, suele ser la que más espacio ocupa, pero docker system prune la excluye deliberadamente para preservar el rendimiento de la compilación.

Para apuntar específicamente a la caché de compilación:

docker builder prune

Si deseas ser selectivo y conservar las capas de caché recientes, utiliza filtros basados en el tiempo:

docker builder prune --filter "until=24h"

Esto elimina solo las capas de caché con más de 24 horas de antigüedad, manteniendo intacto tu trabajo reciente.

Limpia los volúmenes de forma segura.

Los volúmenes requieren especial precaución, ya que contienen datos persistentes, como bases de datos, archivos cargados y el estado de las aplicaciones. Si eliminas el volumen incorrecto, perderás los datos de forma permanente.

En primer lugar, identifica los volúmenes colgantes (los que no están vinculados a ningún contenedor):

docker volume ls -f dangling=true

Revisa esta lista cuidadosamente. Si estás seguro de que estos volúmenes no son necesarios, elimínalos:

docker volume prune

Docker te pedirá confirmación antes de continuar. En caso de duda, haz una copia de seguridad de los volúmenes antes de realizar la poda.

Paso 3: Gestionar el agotamiento del archivo de registro de Docker

Los registros de contenedores pueden consumir silenciosamente grandes cantidades de espacio en disco, a veces superando los 50 GB por contenedor.

Identificar archivos de registro inflados

El controlador de registro predeterminado de Docker json-file captura todos los contenedores stdout y stderr en archivos JSON. Sin una configuración de tamaño máximo (el valor predeterminado es -1, ilimitado), estos archivos crecen sin límites.

Comprueba los tamaños de los contenedores en todos los entornos:

docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Size}}"

Para comprobar el tamaño del archivo de registro de un contenedor específico:

ls -lh $(docker inspect --format='{{.LogPath}}' <container-name>)

Solo para Linux nativo, busca directamente los archivos de registro más grandes:

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

Si docker logs se vuelve lento o los contenedores no se inician, es probable que la causa sean los registros de gran tamaño. Para resolver esto, puedes truncar los registros.

Truncar registros de forma segura

Truncar los registros proporcionará más espacio. Sin embargo, nunca elimines los archivos de registro con rm mientras los contenedores estén en ejecución. El demonio Docker mantiene abiertos los manejadores de archivos de estos registros, y al eliminarlos se crean archivos «eliminados pero abiertos» que siguen consumiendo espacio hasta que se reinicia el demonio.

Lo más seguro es truncar los registros a cero:

sudo truncate -s 0 $(docker inspect --format='{{.LogPath}}' <container-name>)

Esto libera espacio inmediatamente sin romper los manejadores de archivos. El contenedor continúa registrando en el mismo archivo.

Paso 4: Solución avanzada de problemas y cuestiones ocultas

Cuando la limpieza estándar falla, es probable que te enfrentes a uno de estos problemas menos comunes, pero igualmente impactantes:

• Agotamiento de inodos: Tu sistema de archivos se ha quedado sin estructuras de metadatos de archivos a pesar de tener espacio libre en disco.

• Archivos eliminados pero abiertos: Procesos que retienen identificadores de archivos eliminados, creando un uso de espacio «fantasma».

• Sobrecarga del disco virtual de Docker Desktop: El archivo host .raw o .vhdx no se reduce después de eliminar datos dentro de la máquina virtual.

Abordemos cada uno de estos escenarios de forma sistemática.

Resolver el agotamiento de inodos

Esto puede deberse a que las aplicaciones crean millones de archivos pequeños, como sesiones PHP, npm node_modules o artefactos de compilación que consumen inodos a un ritmo alarmante.

En primer lugar, verifica el agotamiento de los inodos:

df -i

Usando comandos de Docker (todos los entornos):

docker ps -a | wc -l             # Check container count
docker images | wc -l         # Check image count
docker image prune -a      # Remove unused images to free inodes

Para instalaciones Linux, identifica los directorios con gran cantidad de inodos:

for dir in /var/lib/docker/*/; do
    echo "$dir: $(sudo find $dir -type f 2>/dev/null | wc -l) files"
done

Eliminar imágenes que no se utilizan con docker rmi también libera inodos. Para problemas a nivel de aplicación, implementa la limpieza dentro de los contenedores o utiliza montajes de volumen para archivos temporales.

Manejar archivos eliminados pero abiertos (solo en Linux)

Cuando se elimina un archivo mientras un proceso todavía lo tiene abierto, el sistema de archivos no libera el espacio hasta que el proceso cierra el identificador del archivo (uso de espacio «fantasma»).

Los usuarios de Linux pueden comprobar si esto ocurre buscando entradas «eliminadas» en la lista de archivos abiertos.

Primero, identifica estos archivos:

sudo lsof | grep deleted 

Archivos eliminados de Docker

A continuación, para liberar espacio, reinicia el proceso específico (utilizando el PID de lsof) o reinicia Docker. Una vez hecho esto, si vuelves a ejecutar el comando, los archivos ya no aparecerán, lo que significa que se han eliminado correctamente.

Ahora exploremos la última estrategia avanzada de resolución de problemas, que solo es aplicable a Docker Desktop: la gestión de discos virtuales.

Administración de discos virtuales de Docker Desktop

Docker Desktop almacena los datos en un archivo de disco virtual (.raw en Mac, .vhdx en Windows) que crece dinámicamente, pero no se reduce automáticamente cuando eliminas datos. Recortas imágenes y contenedores, ves cómo aumenta el espacio libre dentro de la máquina virtual, pero tu disco host sigue lleno.

Para gestionar esto, el método más seguro es utilizar fstrim para compactar el disco sin perder datos:

docker run --privileged --pid=host alpine nsenter -t 1 -m -u -i -n fstrim /

Este comando recorta el sistema de archivos de la máquina virtual de Docker Desktop, liberando los bloques no utilizados y devolviéndolos al sistema host. Tus imágenes, contenedores y volúmenes permanecen intactos.

Si prefieres empezar desde cero (esto borra todos los datos), utiliza Configuración de Docker Desktop → Solucionar problemas → Restablecer valores predeterminados de fábrica. 

Advertencia: Esto es destructivo y elimina todas las imágenes, contenedores, volúmenes y configuraciones. Solo debería ser la última opción, en caso de que todo lo demás falle.

Restablecer los valores predeterminados de fábrica

Paso 5: Evita el error «No hay espacio disponible en el dispositivo» de Docker

Ahora que hemos resuelto la crisis inmediata, implementemos cambios estructurales para evitar que se repita. Estas configuraciones requieren planificación, pero aportan enormes beneficios en cuanto a la estabilidad del sistema.

Mover el directorio raíz de Docker (solo Linux)

Los usuarios de Docker Desktop no pueden cambiar fácilmente la ubicación raíz de los datos. En su lugar, puedes:

• Aumentar el espacio en disco: Utiliza los métodos de compactación de discos virtuales descritos en el paso 4.

• Para el backend WSL2: Gestiona los límites a través de un archivo .wslconfig, tal y como se muestra en Configuración de Docker Desktop → Recursos.

Sin embargo, si utilizas Linux y tu partición raíz tiene limitaciones, pero dispones de una partición más grande (quizás un disco dedicado a datos), reubicar el directorio de datos de Docker es una solución permanente.

Primero, detén Docker:

sudo systemctl stop docker

Edita /etc/docker/daemon.json para especificar la nueva ubicación:

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

Migrar los datos existentes para conservar tus imágenes y contenedores:

sudo rsync -aP /var/lib/docker/ /mnt/docker-data/

Por último, reinicia Docker:

sudo systemctl start docker

Docker ahora almacena todos los datos en la nueva ubicación. Verifica con docker info | grep "Docker Root Dir" para confirmar la ruta al nuevo directorio.

Configurar la rotación global de registros

La rotación de registros es la estrategia de prevención más eficaz que he implementado. De forma predeterminada, el controlador json-file de Docker tiene max-size: -1 (ilimitado), lo que supone un desastre en potencia en producción.

Para instalaciones nativas de Linux, edita /etc/docker/daemon.json para aplicar los límites de forma global:

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

Después de editar el archivo, reinicia Docker.

Los usuarios de Docker Desktop no deben editar directamente el archivo /etc/docker/daemon.json. En su lugar:

1. Abre Docker Desktop.
2. Ve a Configuración → Motor Docker.
3. Verás un editor JSON con la configuración del demonio.
4. Añade la configuración de rotación de registros al JSON existente:

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

Por último, haz clic en Aplicar y reiniciar.

Esta configuración de ejemplo limita cada contenedor a tres archivos de registro de 10 MB cada uno (30 MB en total por contenedor).

Nota crítica: Esta configuración solo se aplica a los contenedores recién creados. Los contenedores existentes conservan su configuración de registro original. Debes volver a crear los contenedores para aplicar los nuevos límites.

Para obtener una compresión y un rendimiento aún mejores, considera el controlador de registro local:

{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "compress": "true"
  }
}

Además, también puedes anular la configuración de registro por servicio en docker-compose.yml:

services:
  web:
    image: nginx
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "5"

Automatizar el mantenimiento

Otra buena práctica es automatizar ciertos procesos. A menudo se dice que más vale prevenir que curar. Por lo tanto, recomiendo automatizar la limpieza con una tarea cron que se ejecute durante las ventanas de mantenimiento:

# Create a cleanup script
sudo cat > /usr/local/bin/docker-cleanup.sh << 'EOF'
#!/bin/bash
docker system prune -f
docker builder prune -f --filter "until=168h"
EOF

sudo chmod +x /usr/local/bin/docker-cleanup.sh

# Add to crontab to run weekly on Sundays at 2 AM
echo "0 2 * * 0 /usr/local/bin/docker-cleanup.sh" | sudo crontab -

Este script crea una tarea programada que elimina automáticamente los contenedores detenidos y los datos no utilizados todos los domingos a las 2 a. m. También elimina de forma segura las capas de caché de compilación con más de una semana (168 horas) de antigüedad para evitar que el uso del disco crezca indefinidamente.

Además, optimiza tus archivos Dockerfiles utilizando compilaciones multietapa para minimizar el tamaño de las imágenes. Las compilaciones en varias etapas te permiten utilizar una etapa para compilar y construir (con todas las herramientas de desarrollo pesadas) y, a continuación, copiar solo los artefactos finales a una etapa de producción limpia y mínima. 

Esto elimina las dependencias de compilación, el código fuente y los archivos intermedios de tu imagen final, lo que reduce drásticamente su tamaño y superficie de ataque.

# Build stage
FROM node:16 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM node:16-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Este patrón reduce el tamaño de la imagen de producción al excluir las herramientas de compilación y el código fuente.

Conclusión

La solución al error «no hay espacio disponible en el dispositivo» sigue un patrón predecible: primero diagnostica para comprender si se trata de bloques de disco o inodos, elimina de forma segura para recuperar espacio sin pérdida de datos y, a continuación, optimiza la configuración para evitar que se repita.

A lo largo de mis años gestionando entornos Docker, he aprendido que la rotación de registros es la estrategia de prevención más eficaz. Una simple configuración de daemon.json puede evitar la mayoría de los incidentes de agotamiento del espacio.

Te recomiendo que compruebes ahora mismo la configuración de daemon.json. Si no tienes configurados max-size y max-file para tu controlador de registro, añádelos inmediatamente. Tu yo futuro te lo agradecerá cuando evites la próxima crisis espacial.

¿Listo para convertirte en un experto en Docker? El siguiente paso es inscribirte en nuestro curso Contenedorización y virtualización con Docker y Kubernetes, que te recomiendo encarecidamente en el programa de habilidades.