SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Docker prune: liberar espaço em disco no VPS

Veja se imagens, containers, cache de build ou volumes ocupam o disco do VPS e use o prune certo, evitando apagar dados importantes sem possibilidade de desfazer.

Identifique o que está a usar o espaço em disco antes de remover qualquer coisa

O Docker ocupa espaço em disco num VPS em quatro áreas: imagens, contentores parados, cache de compilação e volumes locais. Execute primeiro docker system df para descobrir qual delas ocupa o espaço. Depois, execute o comando de remoção mais específico que resolva o problema. A ordem é importante, porque o último comando deste guia, docker volume prune -a, elimina dados e não pode ser desfeito.

Comece pelo sistema de ficheiros, não pelo 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 mostra a gravidade do problema. du mostra onde o espaço foi usado. A opção -x limita du a um único sistema de ficheiros. Assim, não segue um ponto de montagem para um volume separado nem contabiliza esse espaço duas vezes. Os diretórios relevantes dependem do backend de armazenamento. Numa instalação nova do Docker Engine 29.0 ou posterior, o armazenamento de imagens containerd é o padrão. Os conteúdos das imagens e os snapshots dos contentores ficam em /var/lib/containerd. Por isso, a segunda linha du está incluída. Em qualquer dos backends, há dois diretórios importantes em /var/lib/docker: volumes contém os dados dos volumes, e containers contém os metadados dos contentores e os ficheiros de log. Um host atualizado a partir de uma versão mais antiga do Docker mantém a estrutura clássica overlay2 até a alterar. Nessa estrutura, há mais três diretórios relevantes: overlay2 contém as camadas das imagens e dos contentores, buildkit contém a cache de compilação, e image contém os metadados das camadas. docker info | grep -i driver-type apresenta io.containerd.snapshotter.v1 no armazenamento de imagens containerd e nada em overlay2. O armazenamento de imagens containerd mantém a cópia comprimida e a cópia extraída de cada camada. Por isso, as mesmas imagens ocupam mais espaço em disco do que ocupavam em overlay2.

Há uma nota importante sobre sudo e os wildcards da shell, porque isto desperdiça muito tempo. /var/lib/docker pertence a root e não pode ser lido pelo utilizador normal. Por isso, ls /var/lib/docker devolve Permission denied. Um comando como sudo du -sh /var/lib/docker/* também falha, porque a shell expande * antes de sudo ser executado, e a shell não consegue ler esse diretório. Todos os comandos abaixo usam find ou --max-depth em vez de um wildcard precisamente por esse motivo.

Agora, consulte a visão do próprio 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

Estes valores vêm de uma máquina e não dizem nada sobre a sua. Observe antes a estrutura dos resultados. TOTAL contabiliza os objetos, ACTIVE contabiliza os que estão atualmente em uso, e RECLAIMABLE é a estimativa do Docker sobre o espaço que uma operação de remoção poderia libertar nessa linha.

Há dois aspetos de RECLAIMABLE que costumam causar confusão. As camadas de imagem partilhadas são contabilizadas uma vez por cada imagem que as utiliza. Por isso, a linha das imagens normalmente indica mais espaço do que o que será realmente libertado. Além disso, RECLAIMABLE nunca inclui ficheiros de log dos contentores, porque o Docker não trata um ficheiro de log como um objeto recuperável. Quando du indica um diretório muito maior do que o valor apresentado por docker system df, a causa são os ficheiros de log. Há uma secção sobre isso mais abaixo.

Adicione -v para obter a discriminação por objeto.

docker system df -v

Isto divide o resumo numa secção para cada tipo de objeto. A secção das imagens adiciona as colunas SHARED SIZE e UNIQUE SIZE, para poder ver quanto uma única imagem realmente ocupa. A secção dos volumes adiciona uma contagem LINKS, que indica quantos contentores estão ligados a esse volume. Lembre-se de LINKS, porque o valor 0 significa que nenhum contentor usa o volume. Essa é a condição inicial de todos os comandos de remoção de volumes.

Imagens dangling e imagens não utilizadas

Estas duas expressões parecem intercambiáveis, mas não são. Os filtros comportam-se de forma diferente porque os objetos são diferentes.

Uma imagem dangling é uma imagem sem tag. Ela aparece como <none> em docker images. É criada uma em cada rebuild: docker build -t myapp:latest . move a tag myapp:latest para a imagem nova, e a imagem antiga mantém todas as camadas, mas perde o nome. Nada faz referência a ela, e nenhum processo a limpa automaticamente.

Uma imagem não utilizada é qualquer imagem, com ou sem tag, à qual nenhum container faz referência atualmente. Uma postgres:16 que tenha sido obtida no mês passado e à qual nenhum container faça referência, esteja em execução ou parado, não é utilizada, mas não é dangling.

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

A segunda opção faz primeiro uma pergunta.

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

Leia atentamente essa pergunta. "Associated to them" significa um objeto container existente, em execução ou parado. Se executou docker compose down, os containers foram removidos. Portanto, todas as imagens utilizadas por esses serviços passam a estar não utilizadas, e -a remove-as todas. Nada é perdido de forma irrecuperável, mas o docker compose up -d seguinte volta a obter ou recriar tudo, consumindo largura de banda e tempo de build num VPS pequeno. Esta é uma razão prática para saber o que docker compose down remove e o que stop deixa em execução antes de fazer a limpeza.

Um filtro exclui do âmbito as imagens recentes.

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

Isso remove as imagens não utilizadas criadas há mais de 240 horas (10 dias) e mantém as mais recentes. O valor until aceita uma string de duração Go, como 240h, ou um timestamp absoluto, como 2026-08-01T00:00:00.

O que é a cache de build e por que ela cresce tanto

O BuildKit é o builder que o Docker usa por padrão para docker build e docker compose build desde o Docker Engine 23.0. Ele coloca em cache o resultado de cada etapa de cada Dockerfile que executa. No layout overlay2 clássico, mantém essa cache em /var/lib/docker/buildkit. A cache explica por que o segundo build termina em segundos. Portanto, ela está a cumprir a sua função. O Docker Engine executa a recolha de lixo por padrão. A cache que não é usada há 60 dias é removida. O restante só é reduzido quando ultrapassa os limites que o Docker Engine calcula com base no tamanho do disco. Num VPS pequeno, isso pode significar que o disco já está quase cheio. Se fizer build da mesma imagem 50 vezes com uma etapa COPY que muda em cada execução, continuará a ter 50 conjuntos de camadas até a recolha ser executada.

A cache de build não é visível para docker image prune. É um tipo de objeto separado, com o seu próprio comando.

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

Nenhuma destas operações altera as suas imagens ou os seus dados. O único custo de limpar a cache de build é o próximo build demorar mais uma vez. Num VPS que refaz imagens regularmente, Build Cache é muitas vezes a maior linha em docker system df, o que faz dela o maior elemento que pode eliminar com segurança.

Os comandos de limpeza, ordenados do mais seguro ao mais destrutivo

Percorra esta lista e pare assim que df -h / voltar a apresentar um estado saudável. Cada comando imprime uma linha Total reclaimed space: quando termina.

  1. docker container prune remove os contentores parados. As respetivas camadas graváveis também são removidas, por isso tudo o que um contentor tiver escrito fora de um volume é eliminado com ele. Os volumes não são alterados.
  2. docker image prune remove apenas as imagens dangling. Este é o comando de imagens mais seguro.
  3. docker builder prune remove a cache de compilação dangling. O custo é uma compilação mais lenta.
  4. docker image prune -a remove todas as imagens que não sejam referenciadas por nenhum contentor. O custo é voltar a descarregá-las ou compilá-las novamente.
  5. docker system prune executa os três primeiros passos de uma vez e adiciona as redes não utilizadas.
  6. docker volume prune remove os volumes anónimos não utilizados.
  7. docker volume prune -a remove os volumes não utilizados, incluindo os nomeados. Este é o comando que elimina bases de dados.

docker system prune indica o seu próprio âmbito antes de ser executado.

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]

Os volumes são omitidos deliberadamente dessa lista. Adicionar --volumes inclui novamente os volumes anónimos no âmbito. Adicionar -a alarga o passo das imagens, passando de imagens dangling para todas as imagens não utilizadas. Executar um docker system prune -a --volumes -f completo num host de produção é uma forma de perder dados ao tentar libertar espaço.

Por que a remoção de volumes elimina a sua base de dados

Esta é a secção que deve ler duas vezes.

Um volume é considerado não utilizado quando nenhum contentor está associado a ele. Esse é o único critério. O Docker não verifica se o volume está vazio, se um ficheiro Compose ainda o declara ou se contém a única cópia da sua base de dados. LINKS 0 em docker system df -v significa não utilizado, e docker volume prune -a trata todos os volumes não utilizados como candidatos à remoção, exceto se um filtro label que adicionou os excluir.

Agora execute duas ações comuns em sequência. Executa docker compose down para reiniciar uma stack de forma limpa. Esse comando remove os contentores e mantém os volumes nomeados, exatamente como está documentado. O seu volume do Postgres fica então associado a nenhum contentor. Dez minutos depois, executa docker volume prune -a para libertar espaço, e a base de dados desaparece. Ambos os comandos funcionaram corretamente. A sequência destruiu os dados.

Desde o Docker Engine 23.0 (API version 1.42), o comando simples é mais restrito do que era anteriormente.

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

Um volume anónimo é criado pelo Docker, normalmente porque uma imagem declara VOLUME e nunca lhe atribuiu um nome. Esses volumes costumam conter dados que não pediu para manter. Um volume nomeado, do tipo que escreveu no ficheiro Compose, só é removido quando adiciona -a. As versões mais antigas do Docker removiam ambos com o comando simples. Por isso, não confie em hábitos adquiridos num servidor que entretanto atualizou. A diferença só fica clara quando sabe como os volumes nomeados diferem das montagens bind, porque uma montagem bind não é um volume Docker e nenhum comando prune a afeta.

Verifique antes de remover. Substitua myapp_pgdata pelo nome do volume que está a verificar.

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

O filtro dangling=true aplicado a um volume significa sem referências, não vazio. Listar _data mostra o conteúdo existente. Se encontrar um diretório pgdata ou mysql, pare e faça uma cópia antes de continuar. A mesma destruição pode ocorrer através de docker compose down -v, que remove os volumes nomeados declarados pelo ficheiro Compose, exceto os marcados como external, sem pedir confirmação.

Um volume é o único elemento num host Docker que uma reconstrução não consegue recriar. Por isso, os dados dos volumes devem estar numa cópia de segurança restic executada fora do servidor, onde uma flag escrita incorretamente não os possa afetar.

Quando nada é removido: os ficheiros de log dos containers

Já removeu tudo, docker system df mostra quase nada recuperável e o disco continua cheio. Verifique os logs.

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

Cada container escreve a saída padrão e o erro padrão num ficheiro JSON em /var/lib/docker/containers/. Numa instalação predefinida, max-size não está definido, o que significa que não há limite. Assim, um único container preso num ciclo de falhas pode escrever até encher a partição. Nenhum comando de remoção elimina estes ficheiros, porque os containers que os produzem estão em execução e, por definição, não podem ser removidos dessa forma.

Não elimine o ficheiro. Executar rm num ficheiro de log aberto não liberta espaço, porque o daemon do Docker mantém um descritor de ficheiro aberto e o kernel mantém esses blocos alocados até esse descritor ser fechado. df não irá diminuir. Em vez disso, trunque o ficheiro. Isto mantém o mesmo inode e permite que o daemon continue a escrever.

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

Esta é uma correção temporária. docker logs para esses containers não devolve agora nada, e os ficheiros começam imediatamente a crescer outra vez. A correção efetiva é configurar a rotação, conforme explicado na secção seguinte.

Meça antes e depois, sempre

Nunca tente adivinhar o resultado de um prune. Faça uma medição, execute um comando e faça outra medição.

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

Compare os dois resultados de df. Esse é o único número que determina se o servidor continua a servir. docker system df mostra depois qual linha mudou efetivamente, e cada prune apresenta o seu próprio valor de Total reclaimed space:.

Se df não mudou, mas docker system df indica que foi libertado espaço, um descritor de ficheiro aberto está a manter blocos eliminados, que é o problema do ficheiro de log descrito acima. Se ambos mudaram e o disco fica cheio novamente no prazo de um dia, existe um problema de crescimento e não de limpeza. A solução é configurar a rotação e um job agendado.

Como evitar que o disco volte a ficar cheio

Limite o tamanho dos logs. Crie ou edite /etc/docker/daemon.json.

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

Isto limita a 30 MB os logs de cada contentor criado depois do reinício. Todos os valores em log-opts têm de ser strings, incluindo os valores numéricos. Valide o ficheiro antes de reiniciar, porque um daemon.json malformado impede completamente o arranque do daemon e faz todos os contentores parar.

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

docker info deve agora indicar Logging Driver: json-file. Os limites aparecem na secção LogConfig de docker inspect num contentor criado depois do reinício. Este é o detalhe importante: a definição aplica-se apenas a contentores novos. Os contentores existentes mantêm a configuração com que foram criados, por isso é necessário recriá-los.

docker compose up -d --force-recreate

O mesmo limite pode ser definido por serviço num ficheiro Compose. Esta é a melhor opção quando um serviço particularmente ruidoso precisa do seu próprio valor.

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

Agende uma limpeza restrita. Execute-a semanalmente, limitada a imagens dangling e à cache de builds antigos. Nunca coloque -a ou --volumes numa tarefa agendada, porque uma tarefa executada enquanto uma stack está parada elimina as imagens dessa stack e, com --volumes, começa a eliminar os seus dados.

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

A última linha executa o script manualmente uma vez, para que possa ver o resultado antes de este ser executado sem supervisão. O ficheiro tem de ser executável e o nome não pode conter um ponto, porque run-parts ignora tudo o que não seja executável e tudo o que tenha uma extensão.

Crie um alerta para o espaço livre. Uma limpeza executada depois de o disco ficar cheio é uma recuperação. Um alerta aos 80 por cento é prevenção.

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

Coloque isto no cron com o notificador que já utiliza. O espaço livre é apenas metade do problema, por isso associe o alerta a monitorização da saúde do disco no seu VPS, porque um disco com falhas e um disco cheio fazem ambos parar os seus contentores, mas exigem correções diferentes.

Tudo o que foi apresentado acima pressupõe uma instalação padrão, com a raiz de dados em /var/lib/docker. Se a tiver alterado com a chave data-root em daemon.json, substitua o caminho em todos os comandos. No armazenamento de imagens do containerd, data-root não move os dados de imagens e contentores em /var/lib/containerd, porque essa localização é definida por root em /etc/containerd/config.toml. Configurar corretamente esta disposição numa máquina nova faz parte de configurar o Docker num VPS e é muito mais fácil decidir isso antes de ter 40 GB de contentores na partição errada.

FAQ

O comando docker system prune elimina os meus volumes?

Não. O comando simples remove contentores parados, redes não utilizadas, imagens órfãs e a cache de build não utilizada. O pedido de confirmação lista exatamente esse conjunto. Os volumes só são abrangidos quando adiciona --volumes. Desde o Docker Engine 23.0, essa flag abrange volumes anónimos, não volumes nomeados. Os volumes nomeados são removidos por docker volume prune -a e docker compose down -v. Estes são os dois comandos que exigem cuidado.

Porque é que o disco continua cheio depois de executar docker prune?

Há duas causas habituais. A primeira são os ficheiros de log dos contentores em /var/lib/docker/containers/. Nenhum comando prune os afeta, e eles crescem sem limite até definir max-size. A segunda é um ficheiro eliminado que continua aberto por um processo. Se removeu um log com rm enquanto o respetivo contentor estava em execução, o daemon mantém o descritor de ficheiro aberto e o kernel não liberta os blocos. Por isso, df não apresenta alterações. Compare sudo du -xh --max-depth=1 /var/lib/docker com docker system df para identificar qual das situações se aplica.

Qual é a diferença entre docker image prune e docker image prune -a?

O comando simples remove apenas imagens órfãs, ou seja, imagens que perderam a etiqueta, quase sempre devido a um novo build. A forma -a remove todas as imagens que não são utilizadas por nenhum contentor existente, incluindo imagens etiquetadas que obteve deliberadamente. Depois de um docker compose down, os contentores desaparecem, por isso -a também removerá as imagens dessa stack. Nada é perdido permanentemente, porque o arranque seguinte volta a obtê-las ou a reconstruí-las. No entanto, numa ligação lenta, isso pode demorar bastante.

Como impeço que os logs do Docker encham o disco?

Defina max-size e max-file em log-opts, dentro de /etc/docker/daemon.json, e reinicie o daemon com sudo systemctl restart docker. A definição só se aplica aos contentores criados depois desse reinício. Por isso, recrie os contentores em execução com docker compose up -d --force-recreate. Pode definir as mesmas duas opções por serviço num ficheiro Compose, dentro de uma chave logging. Esta é a opção adequada quando um serviço gera muito mais logs do que os restantes.

É seguro executar docker system prune numa tarefa cron?

O comando simples docker system prune -f é seguro num host onde todas as stacks permanecem em execução. No entanto, remove contentores parados. Por isso, eliminará um contentor que parou deliberadamente e que pretendia reiniciar mais tarde. A tarefa agendada mais segura é docker image prune -f juntamente com docker builder prune -f --filter until=168h. Esta combinação liberta os dois recursos que crescem mais depressa e não pode tocar em nenhum volume. Nunca agende -a nem --volumes.

Este artigo foi útil?