nerdctl build: Build Images on containerd
nerdctl build builds OCI images on containerd using BuildKit, with a Docker-compatible command line.
nerdctl is a Docker-compatible CLI for containerd. Its build command mirrors docker build but runs on containerd and BuildKit, which suits rootless and Kubernetes-native runners.
What it does
nerdctl build sends a build context and Dockerfile to BuildKit (buildkitd) to produce an OCI image stored in containerd. The flags match docker build: -t to tag, -f for the Dockerfile, --build-arg, --target, and --platform. It requires a running buildkitd.
Common usage
nerdctl build -t ghcr.io/org/app:ci \
-f Dockerfile --build-arg NODE_ENV=production .
# build and push in one step
nerdctl build -t ghcr.io/org/app:ci --platform linux/amd64,linux/arm64 \
--output type=image,push=true .Options
| Flag | What it does |
|---|---|
| -t, --tag <name> | Name and tag the image |
| -f, --file <path> | Path to the Dockerfile |
| --build-arg <k=v> | Pass a build-time ARG |
| --target <stage> | Build a specific multi-stage target |
| --platform <list> | Target platform(s) for cross-build |
| --output type=image,push=true | Push the result directly |
In CI
nerdctl build needs buildkitd reachable (a sidecar or host service); without it the build cannot start. On rootless or containerd-based runners it replaces docker build cleanly. For multi-arch, pass --platform and emulation (QEMU) must be set up just as with buildx.
Common errors in CI
"cannot access buildkit: failed to dial" means buildkitd is not running or BUILDKIT_HOST is wrong; start it or set the address. "exec format error" during a cross-platform build means QEMU binfmt is not registered. "failed to authorize" on --output push means the runner is not logged in to the registry.