Docker build command tutorial: options and examples

docker build builds an image from a Dockerfile. For Dockerfile syntax, see Dockerfile for beginners and Dockerfile instructions reference. This page covers the command's options.

Syntax

docker build [OPTIONS] PATH | URL | -

The most common form is:

docker build -t myapp:1.0 .

-t names the image. The final . is the build context: the files in the current directory are sent to the builder, and Docker also reads the Dockerfile from there by default. docker build, docker buildx build, and docker image build are the same command.

Common options

Run docker build --help to see the full list.

Example project

All the examples below use this multi-stage Dockerfile:

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"]

There is also a Dockerfile.dev containing only FROM alpine:3.23 and CMD ["echo", "dev image"].

-t: Build and name an image

$ 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] means this is the second step in the base stage. The test stage was not built: if you do not specify --target, Docker builds only the final stage and the stages it depends on.

--build-arg: Pass a build argument

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

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

The default value of GREETING is hello. After you override it with --build-arg GREETING=hi, the built file contains hi from build. ARG exists only during the build, so do not use it to pass passwords (see Security best practices for why).

-f: Specify a Dockerfile

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

$ docker run --rm greet:dev
dev image

A project can have multiple Dockerfiles, such as Dockerfile.dev and Dockerfile.prod. Note that -f only selects which Dockerfile to read; the final . is still the build context.

--target and --progress plain: Build only the test stage and view full output

$ 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 builds only up to the test stage, which is commonly used to run tests in CI.
• --progress plain shows the full output of RUN commands (hello from build, tests passed). The default output mode collapses the output after a step succeeds.
• --no-cache ensures that RUN actually executes again instead of using the cache.
• Here, grep keeps only the output lines from RUN; #6 0.210 means step 6, 0.210 seconds after it started.

Results

$ 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

All four images are the same size because each adds only a small file to Alpine.

Other common patterns

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

# Build context is a subdirectory; Dockerfile is elsewhere
docker build -f docker/Dockerfile.prod -t myapp ./src

# Pull the base image again and skip 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 .

Related chapters

• Dockerfile for beginners, Dockerfile instructions reference
• Build cache and optimization: how the cache works
• Multi-stage builds: more ways to use --target
• Multi-platform images: --platform
• Common error messages: troubleshooting failed builds

Exercises

Exercise: Using the Dockerfile on this page, build an image with GREETING set to hey, and name it both greet:hey and greet:latest.

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

Updated October 14, 2026