Docker Engine 29 reference · Images
docker build Command (Docker CLI)
Build an image from a Dockerfile and a build context, with tags, build arguments, secrets, targets and platforms.
Docker Engine 29
Syntax
docker build [OPTIONS] PATH | URL | -
Parameters
| Parameter | Description |
|---|---|
-t NAME:TAG |
Tag the image. |
-f FILE |
Dockerfile to use (default ./Dockerfile). |
--build-arg KEY=VALUE |
Set a build argument. |
--target STAGE |
Build up to a stage of a multi-stage Dockerfile. |
--secret id=ID,src=FILE |
Expose a secret to RUN --mount=type=secret. |
--platform LIST |
Target platforms, e.g. linux/amd64,linux/arm64. |
--check |
Only run the Dockerfile linter. |
Examples
printf 'FROM alpine:3.24\nARG GREETING=hi\nRUN echo "$GREETING" > /msg\nCMD ["cat", "/msg"]\n' > Dockerfile
docker build -q --build-arg GREETING=hello -t rc-ref-build:1 . > /dev/null
docker run --rm rc-ref-build:1
docker image rm rc-ref-build:1 > /dev/null
Output
hello
Run this on your computer — see “Get Started” for setup.
printf 'FROM alpine:3.24 AS test\nRUN echo running tests\nFROM alpine:3.24\nCMD echo app\n' > Dockerfile
docker build --check . 2>&1 | grep -E 'JSONArgsRecommended|Check complete' | head -1
Output
Check complete, 1 warning has been found!
Run this on your computer — see “Get Started” for setup.
BuildKit is the default builder: it builds independent stages in parallel and supports cache and secret mounts.
Related
docker image ls· List local images with repository, tag, ID and size; filter dangling images and format the output.docker tag· Give an existing image another name, typically a registry path and version before pushing; tags are pointers to the same image.docker history· Show the layers of an image and the instruction that created each, with sizes, to find what makes it big.- Writing a Dockerfile · tutorial
- Layer Caching and Fast Builds · tutorial