Como listar containers docker?

Saber como listar containers Docker é uma das primeiras habilidades que todo profissional de infraestrutura e DevOps precisa dominar. Esse comando simples, mas poderoso, permite visualizar todos os containers em execução no seu ambiente, além de fornecer informações essenciais como ID, status, porta e nome de cada um deles. Seja você iniciante explorando os fundamentos de containerização ou um profissional que precisa gerenciar ambientes complexos, compreender as diferentes formas de listar e filtrar containers é fundamental para otimizar seu workflow diário.

A Docker oferece várias opções de comando que vão além da simples listagem padrão, permitindo que você customize a visualização conforme suas necessidades específicas. Com variações como listar apenas containers parados, exibir tamanho dos containers, ou filtrar por atributos específicos, você ganha controle total sobre seu ambiente de containerização. Esses conhecimentos práticos são essenciais para quem trabalha com cloud computing, administração de sistemas Linux ou qualquer infraestrutura moderna baseada em containers.

Como Listar Containers Docker: Guia Completo

Gerenciar containers Docker com eficiência passa pelo domínio de um conjunto enxuto, porém versátil, de comandos de listagem. Saber quais containers estão ativos, quais foram pausados e quais já encerraram o ciclo de vida é essencial para qualquer profissional que lida com infraestrutura contemporânea. Docker figura entre as tecnologias mais presentes em ambientes de TI hoje, e conhecer bem sua interface de linha de comando representa um diferencial concreto na carreira.

Comando Básico: docker ps (Listar Containers em Execução)

O comando docker ps é o ponto de partida natural para qualquer operação de listagem. Executado sem argumentos, ele exibe somente os containers que estão ativos no momento da consulta.

A saída padrão apresenta as seguintes colunas:

• CONTAINER ID — identificador único (hash SHA-256 truncado) do container
• IMAGE — imagem Docker utilizada na criação do container
• COMMAND — comando executado internamente no momento da inicialização
• CREATED — tempo decorrido desde a criação
• STATUS — estado atual (Up X minutes, Exited, Paused etc.)
• PORTS — mapeamentos de porta entre host e container
• NAMES — nome atribuído ao container (gerado automaticamente ou definido via --name)

Exemplo de uso:

docker ps

Caso nenhum container esteja ativo, a saída apresentará apenas o cabeçalho das colunas, sem linhas de dados. Isso não indica falha — simplesmente não há instâncias em execução naquele instante.

Listar Todos os Containers (Incluindo os Parados): docker ps -a

A flag -a (ou --all) amplia a listagem para contemplar containers em qualquer estado: ativos, parados (exited), pausados (paused) e criados mas nunca iniciados (created).

docker ps -a

Esse comando é indispensável para diagnóstico. Containers que falharam na inicialização ou foram encerrados manualmente permanecem registrados no sistema até serem explicitamente removidos. Ignorar essa visão pode resultar no acúmulo silencioso de instâncias obsoletas, consumindo espaço em disco e tornando a gestão do ambiente mais trabalhosa.

Principais Opções e Flags do Comando docker ps

O docker ps oferece um conjunto robusto de flags que transformam uma listagem simples em uma ferramenta de consulta precisa. Conhecer cada uma delas elimina a necessidade de recorrer a scripts externos para tarefas do dia a dia.

Filtrar Containers por Status (running, exited, paused, created)

A flag --filter combinada com o critério status permite isolar containers por estado específico:

• docker ps --filter "status=running" — somente containers ativos
• docker ps --filter "status=exited" — somente containers encerrados
• docker ps --filter "status=paused" — somente containers pausados
• docker ps --filter "status=created" — containers criados mas não iniciados

Essa abordagem é mais direta do que usar -a e depois filtrar manualmente a saída com grep.

Exibir Apenas os IDs dos Containers: Flag -q

A flag -q (ou --quiet) suprime todas as colunas e retorna somente os IDs dos containers. Esse comportamento é especialmente útil em pipelines de shell, onde o ID é repassado como argumento para outros comandos Docker.

docker ps -q
docker ps -aq

A combinação -aq devolve os IDs de todos os containers, independentemente do estado — um padrão amplamente adotado em operações em lote.

Limitar o Número de Containers Exibidos: Flag -n

A flag -n (ou --last) recebe um número inteiro e exibe apenas os N containers mais recentes, abrangendo todos os estados.

docker ps -n 5

Esse recurso é valioso em ambientes com dezenas ou centenas de containers, onde a listagem completa dificultaria a análise visual.

Exibir o Tamanho dos Containers: Flag -s

A flag -s (ou --size) acrescenta uma coluna SIZE à saída, apresentando dois valores: o tamanho da camada gravável do container (dados gerados durante a execução) e o tamanho total acumulado, incluindo a imagem base.

docker ps -s

Essa informação é útil para identificar containers que ocupam espaço excessivo em disco, sobretudo em ambientes de desenvolvimento onde logs e arquivos temporários tendem a se acumular.

Formatar a Saída com --format e Templates Go

A flag --format aceita templates da linguagem Go para personalizar completamente a saída. Os campos disponíveis são referenciados com a sintaxe {{.Campo}}:

• {{.ID}} — ID do container
• {{.Names}} — nome do container
• {{.Image}} — imagem utilizada
• {{.Status}} — estado atual
• {{.Ports}} — mapeamento de portas
• {{.Size}} — tamanho (requer -s)

Exemplo que exibe apenas nome e estado:

docker ps --format "{{.Names}}\t{{.Status}}"

Para uma saída em formato de tabela com cabeçalhos:

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

Usando docker container ls: Sintaxe Moderna e Equivalências

A partir do Docker 1.13, a CLI foi reorganizada em grupos de subcomandos mais descritivos. O gerenciamento de containers passou a ser agrupado sob o comando docker container, tornando a interface mais consistente e intuitiva.

Diferença entre docker ps e docker container ls

Na prática, docker ps e docker container ls são funcionalmente idênticos — ambos acionam a mesma API interna do Docker daemon. A distinção é puramente sintática e organizacional. O docker ps é um alias legado mantido por compatibilidade retroativa, enquanto docker container ls segue a estrutura moderna da CLI, que agrupa comandos por recurso: docker container, docker image, docker volume, docker network.

Para quem está iniciando com Docker agora, adotar a sintaxe moderna desde o começo facilita a memorização e promove consistência ao trabalhar com outros subcomandos.

Exemplos Práticos com docker container ls e Suas Flags

Todas as flags do docker ps funcionam de forma idêntica com docker container ls:

• docker container ls — lista containers em execução
• docker container ls -a — lista todos os containers
• docker container ls -q — retorna apenas IDs
• docker container ls --format "table {{.Names}}\t{{.Status}}" — saída formatada
• docker container ls --filter "status=exited" — filtra por estado

Filtragem Avançada de Containers com --filter

A flag --filter (ou -f) é um dos recursos mais poderosos do docker ps. Pode ser aplicada múltiplas vezes no mesmo comando, combinando critérios de forma aditiva — lógica OR dentro do mesmo tipo de filtro e lógica AND entre tipos distintos.

Filtrar por Nome do Container

docker ps -a --filter "name=meu-container"

O filtro por nome aceita correspondências parciais — qualquer container cujo nome contenha a string fornecida será incluído na listagem. Para correspondência exata, é necessário usar âncoras de regex ou combinar com outras flags.

Filtrar por Imagem Utilizada

docker ps -a --filter "ancestor=nginx"
docker ps -a --filter "ancestor=nginx:1.25"

O critério ancestor lista containers originados de uma imagem específica. É possível informar apenas o nome da imagem ou incluir a tag para maior precisão.

Filtrar por Label

Labels são metadados chave-valor atribuídos a containers durante a criação. São amplamente utilizados em ambientes orquestrados para identificar serviços, versões e ambientes de implantação.

docker ps --filter "label=ambiente=producao"
docker ps --filter "label=app"

O primeiro exemplo seleciona containers com o label ambiente igual a producao. O segundo retorna qualquer container que possua a chave app, independentemente do valor atribuído.

Filtrar por Rede (Network)

docker ps --filter "network=minha-rede"

Esse filtro é particularmente útil em arquiteturas com múltiplas redes Docker, onde diferentes serviços estão isolados em segmentos distintos. Compreender redes Docker está diretamente relacionado a conceitos de arquitetura de rede que todo profissional de infraestrutura deve conhecer.

Combinando Comandos para Operações em Lote

A flag -q aliada à substituição de comandos do shell (command substitution) permite executar operações em massa sobre múltiplos containers de forma eficiente. Esse padrão é amplamente adotado em scripts de automação e pipelines de CI/CD.

Parar Todos os Containers de Uma Vez

docker stop $(docker ps -q)

O subcomando docker ps -q devolve os IDs de todos os containers ativos. O shell expande essa lista como argumentos para docker stop, que encerra cada um deles de forma controlada — enviando SIGTERM e aguardando o timeout padrão de 10 segundos antes de acionar SIGKILL.

Remover Todos os Containers Parados

docker rm $(docker ps -aq --filter "status=exited")

Alternativamente, o Docker disponibiliza um comando nativo para limpeza:

docker container prune

O prune remove todos os containers parados de uma só vez, solicitando confirmação interativa. Para uso em scripts automatizados, adicione a flag -f para suprimir essa etapa.

Listar e Inspecionar Variáveis de Ambiente de um Container

Combinando listagem com inspeção, é possível verificar as variáveis de ambiente de todos os containers ativos:

for id in $(docker ps -q); do
  echo "=== Container: $id ==="
  docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' $id
done

Esse padrão é útil em auditorias de segurança, permitindo verificar se credenciais ou configurações sensíveis estão expostas como variáveis de ambiente — prática que deve ser evitada em produção.

Erros Comuns ao Listar Containers e Como Resolver

Mesmo um comando aparentemente simples como docker ps pode gerar erros ou comportamentos inesperados. Conhecer as causas mais frequentes economiza tempo de diagnóstico.

Erro de Permissão (Permission Denied) ao Executar docker ps

A mensagem permission denied while trying to connect to the Docker daemon socket surge quando o usuário atual não tem acesso ao socket Unix do Docker (/var/run/docker.sock). As alternativas para resolver são:

1. Executar com sudo: sudo docker ps — solução imediata, mas não indicada para o uso cotidiano.
2. Adicionar o usuário ao grupo docker: sudo usermod -aG docker $USER — após o comando, é necessário encerrar a sessão e fazer login novamente para que a alteração de grupo entre em vigor.
3. Verificar se o daemon está ativo: sudo systemctl status docker — se o serviço estiver parado, o erro de permissão pode ser consequência do daemon inativo.

Esse tipo de configuração em sistemas Linux é um conhecimento fundamental para quem busca certificação Linux e atua na administração de sistemas.

Container Não Aparece na Listagem: Possíveis Causas

Se um container não aparece nem com docker ps -a, as razões mais prováveis são:

• Contexto Docker diferente: o Docker CLI pode estar apontando para um contexto (cluster remoto, Docker Desktop) distinto do ambiente onde o container foi criado. Verifique com docker context ls e docker context use.
• Container removido automaticamente: instâncias iniciadas com a flag --rm são excluídas assim que encerram a execução, sem deixar registro.
• Namespace diferente: em ambientes com múltiplos usuários ou ferramentas como Podman em modo rootless, os namespaces de containers podem ser isolados por usuário.
• Falha durante a criação: o comando docker run pode ter retornado erro antes de registrar o container. Consulte os logs do daemon com journalctl -u docker.

Tabela de Referência Rápida: Comandos para Listar Containers

Docker integra-se diretamente a conceitos de virtualização de servidores e infraestrutura moderna. Dominar os comandos de listagem e filtragem é o alicerce para operar ambientes containerizados com segurança e precisão.

FAQ

Qual é a diferença entre docker ps e docker ps -a?

docker ps exibe apenas os containers que estão ativamente em execução no momento da consulta. docker ps -a (ou --all) inclui todos os containers registrados no sistema, independentemente do estado: ativos, parados, pausados ou criados mas nunca iniciados. Para diagnóstico e limpeza de ambiente, prefira sempre docker ps -a.

Como listar apenas os IDs de todos os containers Docker?

Use a combinação das flags -a e -q: docker ps -aq. O resultado é uma lista com um ID por linha, ideal para scripts de automação e operações em lote como docker stop $(docker ps -aq).

Como filtrar containers Docker pelo nome usando a linha de comando?

Utilize a flag --filter com o critério name: docker ps -a --filter "name=meu-container". O filtro aceita correspondências parciais, retornando todos os containers cujo nome contenha a string informada. Para listar apenas os que estão em execução com aquele nome, basta remover a flag -a.

Como exibir o tamanho de cada container ao listar?

Adicione a flag -s (ou --size) ao comando: docker ps -s ou docker ps -as para abranger todos os containers. A coluna SIZE apresentará dois valores: o tamanho da camada gravável e o tamanho total incluindo a imagem base.

Por que meu container não aparece no docker ps mesmo após iniciá-lo?

As causas mais comuns são: o container foi criado com a flag --rm e já encerrou a execução, sendo removido automaticamente; o Docker CLI está apontando para um contexto diferente do ambiente onde o container foi criado (verifique com docker context ls); ou ocorreu um erro durante a inicialização que impediu o registro da instância. Use docker ps -a para verificar se o container aparece em estado exited.

Como formatar a saída do docker ps para exibir apenas colunas específicas?

Use a flag --format com templates Go. Para mostrar apenas nome e estado: docker ps --format "{{.Names}}\t{{.Status}}". Para incluir cabeçalhos de tabela, adicione o prefixo table: docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}". Os campos disponíveis incluem .ID, .Names, .Image, .Command, .CreatedAt, .Status, .Ports e .Size.

É possível listar containers de todos os namespaces ou contextos Docker?

O Docker CLI opera em um único contexto por vez. Para alternar entre contextos — por exemplo, entre um Docker local e um ambiente remoto — use docker context use nome-do-contexto antes de executar docker ps. Para visualizar todos os contextos disponíveis, utilize docker context ls. Em ambientes Kubernetes gerenciados via Docker Desktop, o contexto determina qual cluster será consultado. Não existe uma flag nativa no docker ps para consultar múltiplos contextos simultaneamente — isso exige scripts que iterem sobre cada contexto configurado.