Skip to content

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.

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

← All tech tips · Suggest a fix

Back to top