Como resolver o problema “Não há mais espaço no dispositivo” do Docker: Um guia completo

O erro do Docker “não há mais espaço no dispositivo” geralmente aparece na pior hora possível: no meio da implantação, durante uma compilação crítica ou ao baixar uma imagem essencial. Já me deparei com esse erro algumas vezes e posso dizer que se apressar em excluir arquivos sem um diagnóstico adequado é uma receita para a perda de dados.

O que torna esse erro especialmente complicado é que ele raramente tem uma única causa. Você pode estar lidando com imagens acumuladas do Docker, logs de contêineres descontrolados, inodes esgotados de milhões de pequenos arquivos ou até mesmo espaço “fantasma” consumido por arquivos excluídos que ainda estão abertos por processos em execução. Cada situação precisa de uma solução diferente.

É por isso que eu sempre falo que é melhor diagnosticar antes de agir. Entender a causa raiz permite que você aplique soluções direcionadas de forma eficiente e evite atrapalhar seu ambiente de produção. Neste guia, vou te mostrar uma maneira sistemática de diagnosticar, resolver e evitar esse problema chato.

Se você é novo no Docker, recomendo fazer nosso curso prático Introdução ao Docker , que aborda tudo o que você precisa para começar a usar a conteinerização.

O que é o erro “Não há espaço disponível no dispositivo” do Docker?

Quando o Docker mostra esse erro, tá indicando um de dois problemas básicos com o armazenamento do seu sistema:

• Esgotamento do bloco do disco físico
• Esgotamento de inodes

Entender a diferença entre essas causas é essencial para aplicar a solução certa.

As causas por trás do erro “não há mais espaço no dispositivo”

A primeira e mais óbvia causa é a falta de espaço no disco físico. Seu sistema de arquivos ficou sem espaço de armazenamento para gravar dados. Esse é o cenário mais intuitivo: você simplesmente encheu seu disco com imagens do Docker, contêineres, logs ou outros arquivos.

A segunda causa, menos óbvia, é o esgotamento do inode. Mesmo com gigabytes de espaço livre disponível, seu sistema de arquivos pode ficar sem inodes (estruturas de metadados usadas para rastrear arquivos e diretórios). Cada arquivo e diretório usa um inode, então aplicativos que criam milhões de arquivos pequenos (tipo arquivos de sessão PHP ou diretórios npm's node_modules ) podem esgotar os inodes e ainda deixar espaço em disco sem usar.

Entendendo o driver de armazenamento overlay2

O Docker normalmente usa o driver de armazenamento overlay2, que é baseado no Linux OverlayFS. O OverlayFS sobrepõe várias pastas em um único host e mostra tudo como um sistema de arquivos único. As camadas de imagem são montadas como diretórios inferiores somente leitura, enquanto cada contêiner em execução adiciona uma camada superior fina gravável. A visualização combinada aparece como um único diretório para o contêiner.

O driver overlay2 suporta nativamente até 128 camadas OverlayFS inferiores, em teoria, mas o armazenamento de camadas do Docker impõe um limite prático de 125 camadas base por imagem. Permite uma composição eficiente de imagens e um melhor desempenho para operações como docker build e docker commit. 

Embora o overlay2 tenha sido projetado para usar menos inodes do que os drivers de armazenamento anteriores, os ambientes Docker que ficam criando imagens, puxando camadas ou fazendo contêineres podem ainda assim pressionar bastante os blocos de disco e os inodes com o tempo, principalmente quando as imagens ou camadas de aplicativos têm muitos arquivos pequenos.

A forma como esse erro aparece depende do ambiente de implantação:

• Em sistemas Linux nativos, isso afeta o sistema de arquivos que suporta /var/lib/docker. 

• No Docker Desktop para Windows ou macOS, a limitação existe dentro da imagem do disco da máquina virtual do Docker (como um arquivo .raw ou .vhdx ), o que traz considerações adicionais ao recuperar ou redimensionar o armazenamento.

Passo 1: Diagnosticar a causa raiz

Antes de tirar qualquer coisa, eu sempre começo com um diagnóstico completo. Esse investimento de alguns minutos pode economizar horas de solução de problemas e evitar a perda acidental de dados.

Verifique a capacidade do sistema

Comece verificando o uso do disco do seu sistema host com o comando ` df -H ` (df significa disk free, ou espaço livre em disco):

df -H

Verificação gratuita do disco no WSL

Esse comando mostra o uso do disco de um jeito fácil de entender. Procure sistemas de arquivos com capacidade próxima a 100%. 

Em instalações nativas do Linux, preste atenção especial à partição onde o /var/lib/docker fica. Normalmente, é a partição raiz (/) ou uma partição Docker dedicada. 

No Docker Desktop (Windows/Mac), procure a montagem do sistema de arquivos principal (normalmente /dev/sdf ou algo parecido), que guarda os dados da VM do Docker, em vez de referências específicas do /var/lib/docker, já que o Docker roda dentro de uma máquina virtual.

Depois, dá uma olhada se os inodes estão acabando usando o comando ` df -i`:

df -i

Verificação de esgotamento de inodes

Se você vir 100% de uso de inodes (IUse%) em qualquer sistema de arquivos, você encontrou o problema. Esse cenário é bem comum em servidores de compilação e ambientes de CI/CD, onde o Docker cria e destrói contêineres com vários arquivos pequenos várias vezes.

Analise o uso específico do Docker

Agora que já descobrimos se o problema é o espaço em disco ou os inodes, vamos dar uma olhada mais de perto e ver como o Docker usa os recursos. O comando ` docker system df ` dá um resumo geral que funciona em todas as instalações do Docker:

docker system df

Essa saída divide o uso do espaço em quatro categorias: Imagens, contêineres, volumes locais e cache de compilação.

A coluna “ RECLAIMABLE ” é super valiosa. Mostra quanto espaço você pode recuperar sem afetar os contêineres em execução. É super importante entender a diferença entre essas duas métricas: o espaço “ativo” está sendo usado por contêineres em execução, enquanto o espaço “recuperável” pode ser liberado sem problemas.

Para obter detalhes mais específicos, adicione o sinalizador verbose:

docker system df -v

Análise de uso do Docker

Essa saída detalhada lista cada imagem, contêiner e volume individualmente com seus tamanhos, fornecendo a análise granular necessária para identificar os que ocupam muito espaço. Aqui está o que você deve procurar em cada seção:

• Imagens: Mostra o tamanho de cada imagem e se ela está sendo usada no momento. Procure imagens grandes que não estejam sendo usadas ou que estejam duplicadas com tags diferentes. As imagens marcadas como “não utilizadas” podem ser removidas com segurança sem afetar os contêineres em execução.

• Recipientes: Mostra o tamanho da camada gravável para cada contêiner. Se um contêiner parado mostrar um SIZE significativo aqui, ele está gravando dados em seu sistema de arquivos. A coluna " CREATED " ajuda a identificar contêineres antigos que podem ter sido esquecidos.

• Volumes: Mostra o tamanho dos volumes e se eles estão sendo usados. Os volumes marcados como não utilizados são candidatos seguros para remoção, mas sempre verifique se eles não contêm dados importantes antes de eliminá-los.

• Cache de compilação: Muitas vezes o maior consumidor e frequentemente esquecido. Essas são camadas intermediárias de operações de docker build que o Docker mantém para acelerar as compilações seguintes.

Comandos específicos do sistema operacional

Para usuários nativos do Linux que querem uma visão ainda mais detalhada do sistema de arquivos, você pode, se quiser, dar uma olhada diretamente nos subdiretórios para ver quais deles (overlay2, containers, volumes) ocupam mais espaço:

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

Mas, pra quem usa o Docker Desktop, o arquivo ` /var/lib/docker ` fica dentro da máquina virtual escondida do Docker e não dá pra acessar direto. A boa notícia é que o docker system df -v dá todas as informações úteis que você precisa, não importa qual seja a sua plataforma, o que faz dele a abordagem de diagnóstico mais confiável.

Passo 2: Limpar o sistema com o Docker Prune 

Depois de ver onde o espaço está sendo usado, posso recuperá-lo com segurança usando os comandos de poda integrados do Docker. Essas operações são feitas pra tirar só os recursos que não estão sendo usados, minimizando o risco de atrapalhar os serviços que estão funcionando.

Elimine recursos pendentes

O Docker faz a diferença entre recursos “pendentes” e “não usados”. Uma imagem pendente é aquela que não tem tag nem referências de contêiner. Normalmente, uma camada intermediária de uma compilação que falhou ou foi substituída. É sempre seguro removê-los.

Comece com o comando básico prune:

docker system prune

Isso remove todos os contêineres, redes e imagens pendentes não utilizados. Não vai mexer nas imagens ou volumes marcados, a menos que seja especificado explicitamente. O Docker vai pedir pra você confirmar antes de continuar.

Para ser mais agressivo e remover todas as imagens não utilizadas (não apenas as pendentes), adicione o sinalizador ` --all `:

docker system prune --all

Sistema Docker prune

Esse comando tira qualquer imagem que não esteja associada a um contêiner no momento. Fique atento: as implantações seguintes vão precisar puxar as imagens removidas de novo.

Se você quiser incluir volumes na limpeza (que têm dados persistentes), adicione o sinalizador ` --volumes `:

docker system prune --all --volumes

Atenção: Isso apaga de vez os dados dos volumes que não estão sendo usados. Sempre verifique se os volumes não têm dados importantes antes de usar essa opção.

Gerenciar o cache de compilação

É aqui que as coisas ficam interessantes. O cache de compilação, que guarda camadas intermediárias das operações de compilação do Docker, costuma ser o que mais ocupa espaço, mas o docker system prune o exclui de propósito pra manter o desempenho da compilação.

Para focar especificamente no cache de compilação:

docker builder prune

Se você quiser ser seletivo e manter as camadas recentes do cache, use filtros baseados no tempo:

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

Isso só tira as camadas de cache com mais de 24 horas, deixando seu trabalho recente intacto.

Limpe os volumes com segurança

Os volumes exigem cuidado extra porque contêm dados persistentes, como bancos de dados, arquivos carregados e estado do aplicativo. Remover o volume errado significa perda permanente de dados.

Primeiro, veja quais volumes estão soltos (aqueles que não estão ligados a nenhum contêiner):

docker volume ls -f dangling=true

Dá uma olhada nessa lista com atenção. Se você tiver certeza de que esses volumes não são necessários, elimine-os:

docker volume prune

O Docker vai pedir pra você confirmar antes de continuar. Se tiver dúvidas, faça backup dos volumes antes de fazer a poda.

Passo 3: Lidando com o esgotamento do arquivo de log do Docker

Os registros dos contêineres podem ocupar muito espaço em disco sem a gente perceber, às vezes passando de 50 GB por contêiner.

Identifique arquivos de log inchados

O driver de registro padrão do Docker json-file captura todos os stdout e stderr dos contêineres em arquivos JSON. Sem uma configuração de tamanho máximo (o padrão é -1, ilimitado), esses arquivos crescem sem limites.

Verifique os tamanhos dos contêineres em todos os ambientes:

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

Para ver o tamanho do arquivo de log de um contêiner específico:

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

Só para Linux nativo, dá pra achar os maiores arquivos de log direto:

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

Se o docker logs ficar lento ou os contêineres não conseguirem iniciar, provavelmente é por causa de logs muito grandes. Para resolver isso, você pode cortar os registros.

Cortar logs com segurança

Cortar os registros vai liberar mais espaço. Mas, nunca apague os arquivos de log com o comando ` rm ` enquanto os contêineres estiverem rodando. O daemon do Docker mantém os identificadores de arquivos abertos para esses logs, e excluí-los cria arquivos “excluídos, mas abertos” que continuam ocupando espaço até que o daemon seja reiniciado.

A abordagem segura é cortar os registros para zero:

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

Isso libera espaço na hora, sem quebrar os identificadores de arquivo. O contêiner continua registrando no mesmo arquivo.

Passo 4: Solução avançada de problemas e questões ocultas

Quando a limpeza padrão não dá certo, você provavelmente tá lidando com um desses problemas menos comuns, mas igualmente impactantes:

• Esgotamento de inodes: Seu sistema de arquivos ficou sem estruturas de metadados de arquivos, mesmo tendo espaço livre em disco.

• Arquivos excluídos, mas abertos: Processos que mantêm identificadores de arquivos excluídos, criando uso de espaço “fantasma”

• Disco virtual do Docker Desktop inchado: O arquivo host .raw ou .vhdx não diminui depois que você apaga os dados dentro da VM.

Vamos abordar cada um desses cenários de forma sistemática.

Resolva o esgotamento do inode

Isso pode ser causado por aplicativos que criam milhões de pequenos arquivos, como sessões PHP, npm node_modules ou artefatos de compilação que consomem inodes em taxas alarmantes.

Primeiro, dá uma olhada se os inodes estão acabando:

df -i

Usando comandos Docker (todos os ambientes):

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 instalações Linux, identifique diretórios com muitos inodes:

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

Remover imagens que não estão sendo usadas com o comando ` docker rmi ` também libera inodes. Para problemas no nível do aplicativo, faça uma limpeza dentro dos contêineres ou use montagens de volume para arquivos temporários.

Lidar com arquivos excluídos, mas abertos (só no Linux)

Quando um arquivo é apagado enquanto um processo ainda o tem aberto, o sistema de arquivos não libera o espaço até que o processo feche o identificador do arquivo (uso de espaço “fantasma”).

Se você usa Linux, dá pra conferir se isso tá rolando procurando por entradas “excluídas” na lista de arquivos abertos.

Primeiro, identifique estes arquivos:

sudo lsof | grep deleted 

Arquivos excluídos do Docker

Então, para liberar espaço, reinicie o processo específico (usando o PID de lsof) ou reinicie o Docker. Depois de fazer isso, se você executar o comando de novo, os arquivos não aparecerão mais, o que significa que foram removidos corretamente.

Vamos agora explorar a última estratégia avançada de resolução de problemas, que só vale para o Docker Desktop: gerenciar discos virtuais.

Gerenciando discos virtuais do Docker Desktop

O Docker Desktop guarda os dados num arquivo de disco virtual (.raw no Mac, .vhdx no Windows) que cresce de forma dinâmica, mas não encolhe automaticamente quando você apaga os dados. Você apaga imagens e contêineres, vê o espaço livre dentro da VM aumentar, mas o disco do seu host continua cheio.

Para fazer isso, a maneira mais segura é usar o comando ` fstrim ` para compactar o disco sem perder dados:

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

Esse comando limpa o sistema de arquivos da VM do Docker Desktop, liberando blocos não usados de volta para o seu sistema host. Suas imagens, contêineres e volumes continuam intactos.

Se você quiser começar do zero (isso apaga todos os dados), use Configurações do Docker Desktop → Solucionar problemas → Redefinir para os padrões de fábrica. 

Atenção: Isso é destrutivo e remove todas as imagens, contêineres, volumes e configurações. Só deve ser a última opção, caso tudo o resto não dê certo.

Redefinir para os padrões de fábrica

Passo 5: Evite o erro “Não há mais espaço no dispositivo” do Docker

Agora que resolvemos a crise imediata, vamos implementar mudanças estruturais para evitar que isso volte a acontecer. Essas configurações exigem planejamento, mas trazem muitos benefícios para a estabilidade do sistema.

Mova o diretório raiz do Docker (só no Linux)

Os usuários do Docker Desktop não conseguem mudar facilmente a localização da raiz dos dados. Em vez disso, você pode:

• Aumentar o espaço em disco: Use os métodos de compactação do disco virtual descritos na Etapa 4.

• Para o backend WSL2: Gerencie os limites por meio de um arquivo ` .wslconfig `, como mostrado em Configurações do Docker Desktop → Recursos.

Mas, se você estiver no Linux e sua partição raiz estiver limitada, mas tiver uma partição maior disponível (talvez um disco de dados dedicado), mudar o diretório de dados do Docker é uma solução permanente.

Primeiro, desligue o Docker:

sudo systemctl stop docker

Edite o arquivo ` /etc/docker/daemon.json ` para colocar o novo local:

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

Mude os dados que já tem pra guardar suas imagens e contêineres:

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

Por fim, reinicie o Docker:

sudo systemctl start docker

Agora, o Docker guarda todos os dados no novo lugar. Dá uma olhada em docker info | grep "Docker Root Dir" pra confirmar o caminho pro novo diretório.

Configurar a rotação global de registros

A rotação de logs é a estratégia de prevenção mais eficaz que já implementei. Por padrão, o driver json-file do Docker tem max-size: -1 (ilimitado), o que é um desastre à espera de acontecer na produção.

Para instalações nativas do Linux, edite /etc/docker/daemon.json para aplicar limites globalmente:

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

Depois de editar o arquivo, reinicie o Docker.

Se você usa o Docker Desktop, não precisa mexer diretamente no arquivo ` /etc/docker/daemon.json `. Em vez disso:

1. Abra o Docker Desktop
2. Vá para Configurações → Docker Engine
3. Você vai ver um editor JSON com a configuração do daemon.
4. Adicione as configurações de rotação de log ao JSON que já existe:

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

Por fim, clique em Aplicar e Reiniciar.

Essa configuração de exemplo limita cada contêiner a três arquivos de log de 10 MB cada (30 MB no total por contêiner).

Observação importante: Essas configurações só valem para contêineres recém-criados. Os contêineres existentes mantêm a configuração original de log. Você precisa recriar os contêineres para aplicar os novos limites.

Para uma compressão e desempenho ainda melhores, considere o driver de registro local:

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

Além disso, você também pode substituir as configurações de log por serviço em docker-compose.yml:

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

Automatizar a manutenção

Outra boa prática é automatizar certos processos. Costuma-se dizer que é melhor prevenir do que remediar. Então, recomendo automatizar a limpeza com uma tarefa cron que rola durante as janelas de manutenção:

# 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 -

Esse script cria uma tarefa agendada que remove automaticamente os contêineres parados e os dados não usados todos os domingos às 2h da manhã. Ele também limpa com segurança as camadas de cache de compilação com mais de uma semana (168 horas) para evitar que o uso do disco cresça sem parar.

Além disso, otimize seus Dockerfiles usando compilações em várias etapas para minimizar o tamanho das imagens. As compilações em várias etapas permitem que você use uma etapa para compilar e construir (com todas as ferramentas de desenvolvimento pesadas) e, em seguida, copie apenas os artefatos finais para uma etapa de produção limpa e mínima. 

Isso elimina dependências de compilação, código-fonte e arquivos intermediários da sua imagem final, reduzindo drasticamente seu tamanho e a superfície 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"]

Esse padrão reduz o tamanho da imagem de produção, tirando as ferramentas de compilação e o código-fonte.

Conclusão

A correção do erro “não há mais espaço no dispositivo” segue um padrão previsível: primeiro, faça um diagnóstico para entender se você está lidando com blocos de disco ou inodes, faça uma limpeza segura para recuperar espaço sem perda de dados e, em seguida, otimize a configuração para evitar a recorrência.

Ao longo dos anos em que gerenciei ambientes Docker, aprendi que a rotação de logs é a estratégia de prevenção mais eficaz. Uma configuração simples do daemon.json pode evitar a maioria dos problemas de falta de espaço.

Recomendo que você verifique agora mesmo a configuração do seu daemon.json. Se você não tiver max-size e max-file configurados para o seu driver de registro, adicione-os imediatamente. Seu eu futuro vai te agradecer quando você evitar a próxima crise de espaço.

Pronto pra virar um craque no Docker? Então, o próximo passo é se inscrever no nosso Containerização e Virtualização com Docker e Kubernetes, que eu recomendo muito para o programa.