# nerdctl build: Build Images on containerd

> nerdctl build builds OCI images on containerd with BuildKit, Docker-compatible flags. Reference for -t, --build-arg, --platform, and CI errors.

Source: https://latchkey.dev/learn/command-reference/nerdctl-build  
Updated: 2026-06-30

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.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt