Tutorial de docker build: parâmetros e exemplos

docker build cria uma imagem com base em um Dockerfile. Para aprender a escrever um Dockerfile, consulte Introdução ao Dockerfile e Referência completa das instruções do Dockerfile. Esta página reúne os parâmetros do próprio comando.

Sintaxe

docker build [parâmetros] caminho-do-contexto-de-build

O formato mais comum:

docker build -t myapp:1.0 .

-t dá um nome à imagem. O . no final é o contexto de build (build context): os arquivos da pasta atual são enviados ao processo de build, e o Dockerfile também é lido dessa pasta por padrão. docker build, docker buildx build e docker image build são o mesmo comando.

Parâmetros mais usados

Execute docker build --help para ver a lista completa.

Projeto de exemplo

Todos os exemplos a seguir usam este Dockerfile com vários estágios:

FROM alpine:3.23 AS base
ARG GREETING=hello
RUN echo "$GREETING from build" > /greeting.txt

FROM base AS test
RUN cat /greeting.txt && echo "tests passed"

FROM base
CMD ["cat", "/greeting.txt"]

Há também um Dockerfile.dev, cujo conteúdo é apenas FROM alpine:3.23 e CMD ["echo", "dev image"].

-t: construir e nomear

$ docker build -t greet .

[+] Building 0.6s (6/6) FINISHED                                                                                                       docker:default
 => [internal] load build definition from Dockerfile                                                                                             0.0s
 => => transferring dockerfile: 235B                                                                                                             0.0s
 => [internal] load metadata for docker.io/library/alpine:3.23                                                                                   0.1s
 => [internal] load .dockerignore                                                                                                                0.0s
 => => transferring context: 2B                                                                                                                  0.0s
 => CACHED [base 1/2] FROM docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                 0.0s
 => => resolve docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                             0.0s
 => [base 2/2] RUN echo "hello from build" > /greeting.txt                                                                                       0.3s
 => exporting to image                                                                                                                           0.1s
 => => exporting layers                                                                                                                          0.0s
 => => exporting manifest sha256:0d0e8696cb61970ffeebe21706f795d44bb7fdb22662a328bd83a22c9cb91d60                                                0.0s
 => => exporting config sha256:04f0467aef1baf360852e9f8633e676c7cbbcbe454d0827bbdd474dcda4a7d1f                                                  0.0s
 => => exporting attestation manifest sha256:186d1197793b26cefb32e3555067d8caaa7d626310efb2c1eeb6c42bfefb01a1                                    0.0s
 => => exporting manifest list sha256:2632bf33adbcb3cffc3697245d5e0ad0d239b58b46413d39f87e29cbbebfb3ef                                           0.0s
 => => naming to docker.io/library/greet:latest                                                                                                  0.0s
 => => unpacking to docker.io/library/greet:latest                                                                                               0.0s

$ docker run --rm greet
hello from build

[base 2/2] indica que essa é a segunda etapa do estágio base. O estágio test não foi construído: sem especificar --target, o build inclui apenas o último estágio e os estágios dos quais ele depende.

--build-arg: passar parâmetros de build

$ docker build -q --build-arg GREETING=hi -t greet:hi .
sha256:c6f108c2247535f2ee548ef5868bdf83911f06e7ecfeab0fb58eb47b19c79154

$ docker run --rm greet:hi
hi from build

O valor padrão de GREETING é hello. Ao substituí-lo com --build-arg GREETING=hi, o conteúdo do arquivo criado pelo build passa a ser hi from build. ARG só existe durante o build; não o use para passar senhas (veja o motivo em Práticas recomendadas de segurança).

-f: especificar o Dockerfile

$ docker build -q -f Dockerfile.dev -t greet:dev .
sha256:59849c87b388414a149e72c98ff88d30d9b575f5240625c0b8f58332ce5103fb

$ docker run --rm greet:dev
dev image

Um mesmo projeto pode ter vários Dockerfiles, por exemplo, Dockerfile.dev e Dockerfile.prod. Lembre-se de que -f escolhe qual Dockerfile ler; o contexto de build continua sendo o . final.

--target e --progress plain: construir apenas a etapa de teste e ver a saída completa

$ docker build --target test --progress plain --no-cache . 2>&1 | grep -E "^#[0-9]+ [0-9.]+ |DONE|ERROR" | grep -v DONE
#6 0.210 hello from build
#6 0.210 tests passed

• --target test constrói somente até a etapa test, algo comum para executar testes em CI.
• --progress plain exibe a saída completa das instruções RUN (hello from build e tests passed). No modo padrão, a saída é recolhida quando uma etapa termina com sucesso.
• --no-cache garante que RUN seja executado novamente, em vez de usar o cache.
• Aqui, grep mantém somente as linhas de saída de RUN; #6 0.210 indica a sexta etapa, 0,210 segundo após o início.

Resultado

$ docker build -q --target base -t greet:base .
sha256:b92f520e3598da9bcb7ceb2cf82977090316062325363faae1d65c3630423b8e

$ docker images greet
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
greet:base     b92f520e3598       12.9MB         3.85MB        
greet:dev      59849c87b388       12.9MB         3.85MB        
greet:hi       c6f108c22475       12.9MB         3.85MB        
greet:latest   2632bf33adbc       12.9MB         3.85MB

As quatro imagens têm o mesmo tamanho porque cada uma adiciona apenas um arquivo pequeno ao Alpine.

Outras formas comuns de usar

# Add two tags at the same time
docker build -t myapp:1.2.0 -t myapp:latest .

# The build context is a subfolder; the Dockerfile is elsewhere
docker build -f docker/Dockerfile.prod -t myapp ./src

# Download the base image again and disable the cache (full rebuild)
docker build --pull --no-cache -t myapp .

# Build for an amd64 server (on an Apple Silicon Mac)
docker build --platform linux/amd64 -t myapp .

# Use a secret during the build
docker build --secret id=npm_token,env=NPM_TOKEN -t myapp .

Capítulos relacionados

• Introdução ao Dockerfile, Referência completa das instruções do Dockerfile
• Cache e otimização de build: como o cache funciona
• Builds de vários estágios: mais usos de --target
• Imagens multiplataforma: --platform
• Mensagens de erro comuns: como investigar falhas no build

Exercícios

Exercício: usando o Dockerfile desta página, construa uma imagem com GREETING definido como hey e atribua a ela os nomes greet:hey e greet:latest.

docker build --build-arg GREETING=hey -t greet:hey -t greet:latest .
docker run --rm greet:latest

Atualizado 14 de outubro de 2026