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
Terminal
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.
Frequently asked questions
nerdctl build: Build Images on containerd?
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.
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.
