Did you know?
docker build --check lints a Dockerfile without building the image.
Run it before every push or in CI: it catches mistakes like an ARG used in FROM with no default value.
- DevOps & cloud
- Last checked
Explained
docker build --check runs Docker’s build checks (a built-in Dockerfile linter) and stops there. It doesn’t run any build steps, so it finishes in seconds even for large images.
It catches mistakes that would otherwise fail late or silently. For example, when a base image name depends on a build argument with no default:
ARG BUILD_ENV
FROM build-${BUILD_ENV}The check reports InvalidDefaultArgInFrom, because a plain docker build . would try to use the invalid image name build-. Other rules flag things like secrets passed through ARG or ENV, legacy ENV key value syntax, and stage names that don’t match their case.
Run it in the directory that holds your Dockerfile:
docker build --check .A clean file prints Check complete, no warnings found. Each warning names the rule and links to its documentation. The flag is available in Buildx 0.15 and later, which recent Docker Desktop and Docker Engine releases include. Add it to CI to block a Dockerfile that has warnings.
Learn more
- Using If-Else in Dockerfile: Conditional Builds with ARG, RUN and Multi-Stage Full guide · Updated Nov 2026
