docker build: Usage, Options & Common CI Errors
Build an image from a Dockerfile - and survive the build doing it in CI.
docker build packages a build context and a Dockerfile into an image. In modern Docker it invokes BuildKit by default. This page covers the flags you use most and the build failures that break CI.
What it does
docker build sends a build context (a directory, usually the current one) to the daemon and executes each Dockerfile instruction to produce a layered image. The final argument is the context path, not the Dockerfile path.
Common usage
docker build -t myapp:latest .
docker build -t myapp:1.2.3 -f docker/Dockerfile .
docker build --build-arg NODE_ENV=production -t myapp .
docker build --target builder -t myapp-builder .
docker build --no-cache --pull -t myapp:ci .Options
| Flag | Does |
|---|---|
| -t, --tag | Name and optionally tag (name:tag) |
| -f, --file | Path to the Dockerfile (default ./Dockerfile) |
| --build-arg | Set a build-time ARG value |
| --target | Build a specific stage in a multi-stage build |
| --no-cache | Ignore the layer cache |
| --pull | Always pull a newer base image |
| --platform | Target platform, e.g. linux/amd64 |
Common errors in CI
A frequent CI failure is "failed to compute cache key: ... not found" - the Dockerfile COPYs a path that is not in the build context (often because of .dockerignore or because CI runs from a different working directory). Fix by running build from the repo root with the correct context, e.g. docker build -f path/to/Dockerfile . , and confirm the file is not excluded by .dockerignore. A second is running out of disk: "no space left on device" mid-build - prune with docker system prune -af or use a larger runner.