Tutorial de imagens Docker: pull, images, tag, rmi e estrutura em camadas

Uma imagem (image) é um modelo para criar contêineres. Por trás do docker run nginx:1.30 da seção anterior, o Docker primeiro baixou a imagem nginx:1.30. Nesta seção, você vai aprender como as imagens são nomeadas, baixadas, consultadas e removidas, além de conhecer sua estrutura em camadas.

Componentes do nome de uma imagem

Um nome completo de imagem é assim:

docker.io/library/nginx:1.30-alpine
└───┬───┘ └──┬──┘ └─┬─┘ └────┬────┘
 registry  namespace  nome     tag

As três formas abaixo se referem à mesma imagem:

docker pull nginx
docker pull nginx:latest
docker pull docker.io/library/nginx:latest

Para imagens de outros registries, informe o endereço completo, como ghcr.io/owner/app:1.0 do GitHub e gcr.io/distroless/static-debian13 do Google.

Nomes de tags comuns

As imagens oficiais costumam oferecer várias variantes:

Mais adiante nesta seção, você vai baixar essas três imagens Python e comparar seus tamanhos.

Baixar imagens: docker pull

Se a imagem não estiver no computador, docker run a baixa automaticamente; docker pull apenas baixa, sem executar. Se você executar pull novamente para uma imagem que já tem, o Docker verifica se há atualizações:

$ docker pull nginx:1.30
1.30: Pulling from library/nginx
Digest: sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
Status: Image is up to date for nginx:1.30
docker.io/library/nginx:1.30

Image is up to date significa que a imagem local já está atualizada e não foi baixada novamente. A última linha mostra o nome completo da imagem, incluindo o registry padrão docker.io e o namespace library.

Veja as “camadas compartilhadas”

Agora, baixe outra versão do nginx, a 1.31:

$ docker pull nginx:1.31
1.31: Pulling from library/nginx
ecc510c1e359: Already exists
807ab930f3a0: Pull complete
04bdbc7ea6b5: Pull complete
f7e1db57b58b: Pull complete
8020170dc65f: Pull complete
1efc53192927: Pull complete
947d22046304: Pull complete
Digest: sha256:f9ea18bfa4fad859e1ed38259d711da7ccad2c3516e875cec3351a57c859f571
Status: Downloaded newer image for nginx:1.31
docker.io/library/nginx:1.31

A primeira camada, ecc510c1e359, mostra Already exists: nginx 1.30 e 1.31 começam com a mesma camada base do Debian 13. Essa camada já está no disco e não precisa ser baixada novamente. É isso que a seção 1 chama de “camada base compartilhada da imagem”.

O mesmo acontece ao baixar python:3.14-slim, que também usa Debian 13 como base:

$ docker pull python:3.14-slim
3.14-slim: Pulling from library/python
ecc510c1e359: Already exists
a5883d972f3b: Pull complete
6aaf5b0aae75: Pull complete
bb8166eb34e6: Pull complete
Digest: sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170
Status: Downloaded newer image for python:3.14-slim
docker.io/library/python:3.14-slim

Listar imagens locais: docker images

$ docker images
IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
hello-world:latest   5e2309035332       25.9kB         9.49kB   U
nginx:1.30           9bf97bd7714f        242MB         66.5MB
nginx:1.31           f9ea18bfa4fa        243MB         66.7MB
ubuntu:26.04         f144425ff09b        162MB         45.6MB

O formato de saída de docker images no Docker 29 é diferente do das versões antigas. Os campos antigos eram REPOSITORY TAG IMAGE ID CREATED SIZE, e muitos tutoriais na internet ainda mostram esse formato. Se você vir algo diferente, não se preocupe: o conteúdo é o mesmo.

docker image ls e docker images são o mesmo comando. Formas comuns de filtrar:

$ docker images -q
b9767f56a1cc
a2b82f3c4855
9bf97bd7714f
f9ea18bfa4fa
f6a589d43c42
f144425ff09b
5e2309035332

-q exibe apenas os IDs e costuma ser combinado com outros comandos para processamento em lote. docker images nginx lista apenas nginx, enquanto docker images --filter dangling=true lista imagens “dangling” sem nome (geralmente versões antigas substituídas após uma nova compilação).

Comparando slim, alpine e a versão completa

Baixe também as outras duas versões do Python:

$ docker pull python:3.14-alpine
3.14-alpine: Pulling from library/python
e2de96513ba9: Pull complete
48f6a2588427: Pull complete
2a22c5887fa2: Pull complete
d486488257d0: Pull complete
Digest: sha256:f6a589d43c42b9e7f7dc67a12d37132491f362859a5d750607710cc56da3bc72
Status: Downloaded newer image for python:3.14-alpine
docker.io/library/python:3.14-alpine

$ docker pull python:3.14
3.14: Pulling from library/python
4846f2900730: Pull complete
62fe2e747f69: Pull complete
4dc3950125eb: Pull complete
b2eb680928d4: Pull complete
083b5813628d: Pull complete
9b0ef59a9f4a: Pull complete
6e255bfcc16c: Pull complete
Digest: sha256:b9767f56a1cc620aa72d38cc3557d26412e38a4597c92953476136b78894ccbd
Status: Downloaded newer image for python:3.14
docker.io/library/python:3.14

$ docker images python
IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
python:3.14          b9767f56a1cc       1.63GB          433MB
python:3.14-alpine   f6a589d43c42       82.6MB           21MB
python:3.14-slim     a2b82f3c4855        180MB         45.7MB

Mesmo sendo Python 3.14, a diferença é enorme:

• Versão completa inclui ferramentas de compilação como gcc. É adequada quando você precisa compilar pacotes dentro da imagem (ou como etapa de build de um build em vários estágios).
• slim é uma boa opção para a maioria das aplicações.
• alpine é a menor, mas usa musl em vez de glibc. Alguns pacotes que precisam ser compilados (como certos pacotes Python) são mais difíceis de instalar no Alpine. Se estiver em dúvida, escolher slim costuma ser mais seguro.

Adicione uma tag à imagem: docker tag

docker tag não copia a imagem; apenas adiciona outro nome que aponta para o mesmo conteúdo:

$ docker tag nginx:1.30 myname/nginx:v1

$ docker images --filter reference=nginx:1.30 --filter reference=myname/nginx
IMAGE             ID             DISK USAGE   CONTENT SIZE   EXTRA
myname/nginx:v1   9bf97bd7714f        242MB         66.5MB
nginx:1.30        9bf97bd7714f        242MB         66.5MB

O ID é igual nas duas linhas, o que significa que elas são a mesma imagem. Antes de enviar a imagem para o Docker Hub, você precisa nomeá-la no formato sua-conta/nome:tag dessa maneira. Consulte Enviar para o Docker Hub.

Uma tag não é uma versão fixa

A tag é apenas um "rótulo". Os mantenedores podem apontá-la para um novo conteúdo a qualquer momento; no próximo mês, nginx:1.30 pode apontar para a versão 1.30.6. Quando precisar fixar completamente a versão, use o digest (hash SHA256 do conteúdo):

$ docker images --digests nginx
REPOSITORY   TAG       DIGEST                                                                    IMAGE ID       CREATED      SIZE
nginx        1.30      sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb   9bf97bd7714f   6 days ago   242MB
nginx        1.31      sha256:f9ea18bfa4fad859e1ed38259d711da7ccad2c3516e875cec3351a57c859f571   f9ea18bfa4fa   6 days ago   243MB

docker pull nginx@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb

Ao baixar usando o digest, você sempre obtém exatamente o mesmo conteúdo.

Remova uma imagem: docker rmi

Se algum contêiner, inclusive um que esteja parado, estiver usando essa imagem, não será possível removê-la:

$ docker run -d --name web nginx:1.30
e34409bcf1727f02fc3b0558d202dd057f2116b4a2e9186f83bbed4625842272

$ docker rmi nginx:1.30
Error response from daemon: conflict: unable to delete nginx:1.30 (must be forced) - container e34409bcf172 is using its referenced image 9bf97bd7714f

Remova primeiro o contêiner que a utiliza e, depois, a imagem:

$ docker rm -f web
web

$ docker rmi nginx:1.30
Untagged: nginx:1.30
Deleted: sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb

• Untagged: remove o nome.
• Deleted: a própria imagem só é realmente removida quando nenhum outro nome aponta para ela. Se ainda houver um alias como myname/nginx:v1 apontando para a mesma imagem, você verá apenas Untagged.

Limpe as imagens desnecessárias:

docker image prune      # Remove somente imagens pendentes (sem nome, <none>)
docker image prune -a   # Remove todas as imagens que não estão sendo usadas por contêineres

Estrutura em camadas da imagem: docker history

docker history lista cada camada da imagem e qual instrução do Dockerfile a criou:

$ docker history nginx:1.30
IMAGE          CREATED      CREATED BY                                      SIZE      COMMENT
9bf97bd7714f   6 days ago   CMD ["nginx" "-g" "daemon off;"]                0B        buildkit.dockerfile.v0
<missing>      6 days ago   STOPSIGNAL SIGQUIT                              0B        buildkit.dockerfile.v0
<missing>      6 days ago   EXPOSE map[80/tcp:{}]                           0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENTRYPOINT ["/docker-entrypoint.sh"]            0B        buildkit.dockerfile.v0
<missing>      6 days ago   COPY 30-tune-worker-processes.sh /docker-ent…   16.4kB    buildkit.dockerfile.v0
<missing>      6 days ago   COPY 20-envsubst-on-templates.sh /docker-ent…   12.3kB    buildkit.dockerfile.v0
<missing>      6 days ago   COPY 15-local-resolvers.envsh /docker-entryp…   12.3kB    buildkit.dockerfile.v0
<missing>      6 days ago   COPY 10-listen-on-ipv6-by-default.sh /docker…   12.3kB    buildkit.dockerfile.v0
<missing>      6 days ago   COPY docker-entrypoint.sh / # buildkit          8.19kB    buildkit.dockerfile.v0
<missing>      6 days ago   RUN /bin/sh -c set -x     && groupadd --syst…   88.2MB    buildkit.dockerfile.v0
<missing>      6 days ago   ENV DYNPKG_RELEASE=1~trixie                     0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENV PKG_RELEASE=1~trixie                        0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENV ACME_VERSION=0.4.1                          0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENV NJS_RELEASE=1~trixie                        0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENV NJS_VERSION=1.0.1                           0B        buildkit.dockerfile.v0
<missing>      6 days ago   ENV NGINX_VERSION=1.30.5                        0B        buildkit.dockerfile.v0
<missing>      6 days ago   LABEL maintainer=NGINX Docker Maintainers <d…   0B        buildkit.dockerfile.v0
<missing>      7 days ago   # debian.sh --arch 'amd64' out/ 'trixie' '@1…   87.7MB    debuerreotype 0.17

Leia de baixo para cima:

1. Na parte inferior está a camada base do Debian 13 (trixie), com 87.7 MB.
2. No meio, RUN ... groupadd ... instala o próprio nginx e ocupa 88.2 MB; é a maior camada.
3. COPY adiciona os scripts de inicialização, que ocupam apenas alguns KB.
4. ENV, EXPOSE, CMD e outras instruções apenas configuram a imagem e têm tamanho 0B.

<missing> não é um erro. Significa apenas que essas camadas intermediárias foram construídas em outra máquina e não têm IDs independentes nesta máquina.

As camadas trazem dois benefícios:

• Compartilhamento: quando várias imagens usam o Debian 13 como base, essa camada é armazenada e baixada uma única vez (a mensagem Already exists vista antes).
• Cache: ao construir uma imagem, as camadas que não mudaram podem ser reutilizadas diretamente. Essa é a base do cache de build.

Quando um contêiner é iniciado, o Docker adiciona uma camada gravável sobre essas camadas somente leitura. Os arquivos criados ou alterados dentro do contêiner são gravados nessa camada. Quando o contêiner é removido, ela também desaparece. Por isso, os dados que você precisa preservar devem ficar em um Volume.

No Docker Desktop, você também pode clicar em uma imagem para ver as mesmas informações sobre as camadas:

Ver as configurações da imagem: docker inspect

docker inspect exibe todas as configurações da imagem (um grande bloco de JSON). Use --format para obter apenas os campos necessários:

$ docker inspect --format '{{.Config.Cmd}}' nginx:1.30
[nginx -g daemon off;]

$ docker inspect --format '{{.Os}}/{{.Architecture}}' nginx:1.30
linux/amd64

$ docker inspect --format '{{json .Config.ExposedPorts}}' nginx:1.30
{"80/tcp":{}}

$ docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' nginx:1.30
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
NGINX_VERSION=1.30.5
NJS_VERSION=1.0.1
NJS_RELEASE=1~trixie
ACME_VERSION=0.4.1
PKG_RELEASE=1~trixie
DYNPKG_RELEASE=1~trixie

Assim, você pode descobrir que, por padrão, o contêiner executa nginx -g daemon off; ao iniciar, que esta é a versão linux/amd64, que a porta 80 está exposta e quais variáveis de ambiente vêm incluídas na imagem.

Exportar e importar: docker save / load

Para transferir imagens entre máquinas sem conexão com a internet, você pode salvá-las em um arquivo tar:

$ docker save -o nginx-1.30.tar nginx:1.30

$ ls -lh nginx-1.30.tar
-rw-------    1 root     root       63.4M Oct 12 14:41 nginx-1.30.tar

$ docker rmi nginx:1.30
Untagged: nginx:1.30
Deleted: sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb

$ docker load -i nginx-1.30.tar
Loaded image: nginx:1.30

Copie o arquivo tar para outra máquina e execute docker load para usar a imagem, sem precisar se conectar ao Docker Hub.

Gerenciar imagens com o Docker Desktop

No menu à esquerda do Docker Desktop, clique em Images para ver todas as imagens locais, assim como em docker images. Os botões à direita permitem executá-las ou removê-las diretamente:

Resumo dos comandos

Na próxima seção, você vai conhecer os estados pelos quais um contêiner passa, da criação à remoção.

Resumo

• O nome de uma imagem segue o formato [registry/]repositório:tag; imagens oficiais não têm prefixo.
• Várias imagens compartilham as mesmas camadas inferiores, que são baixadas e armazenadas uma única vez.
• slim é uma boa opção para a maioria dos aplicativos; alpine é menor, mas tem compatibilidade mais limitada.
• docker history mostra qual comando criou cada camada.

Exercícios

Exercício 1: Baixe alpine:3.23 e python:3.14-alpine e observe se Already exists aparece no segundo download.

Exercício 2: Adicione um novo nome, mysite/web:test, a nginx:1.30 e depois remova esse novo nome. nginx:1.30 ainda estará lá?

docker tag nginx:1.30 mysite/web:test
docker rmi mysite/web:test

Atualizado 14 de outubro de 2026