Getting started

This page covers building and running containerd from source for development. For end-user installation, see docs/getting-started.md in the repo and the upstream containerd.io docs.

Prerequisites

• Go — at least one of the two most recent major Go versions. go.mod declares go 1.26.2.
• make, a C toolchain, and git.
• On Linux, kernel headers ≥ 4.12 if you build with the btrfs snapshotter (otherwise pass BUILDTAGS=no_btrfs). The overlayfs snapshotter (default) needs kernel features that stabilized in 4.x.
• For running containers: runc (Linux) or hcsshim/runhcs (Windows) and a working cgroup setup.
• For the CRI integration tests: criu, CNI plugins, crictl. Install with make install-deps.

The full list and the exact pinned versions used by CI live under script/setup/. BUILDING.md documents the full developer setup including a pre-configured Codespaces dev container.

Building

git clone https://github.com/containerd/containerd
cd containerd
make

make (default target all → binaries) produces the binaries in ./bin/:

• bin/containerd — daemon
• bin/containerd-shim-runc-v2 — runc-v2 shim
• bin/ctr — debug CLI
• bin/containerd-stress — stress driver

Build options exposed by the Makefile (see Makefile and Makefile.<os>):

Variable	Purpose
GOOS / GOARCH	Target platform (default: host)
BUILDTAGS	Extra Go build tags, e.g. no_btrfs, no_devmapper, no_zfs
STATIC=1	Static build with osusergo netgo static_build
GODEBUG=1	Disable optimizations, enable -N -l for delve
PREFIX / DESTDIR	Install location for make install

Install the binaries to /usr/local/bin:

sudo make install

Running the daemon

The simplest invocation reads /etc/containerd/config.toml if present and falls back to compiled-in defaults:

sudo containerd

A typical development invocation with explicit paths:

sudo containerd \
  --address /run/containerd/containerd.sock \
  --root /var/lib/containerd \
  --state /run/containerd \
  --log-level debug

The systemd unit containerd.service at the repo root is the supported way to run it as a service.

Generating a default config

containerd config default > /etc/containerd/config.toml

Use containerd config dump to see the effective config (defaults merged with the config file). Both subcommands are implemented in cmd/containerd/command/config.go.

Testing

Command	What it runs
make test	Unit tests that don't require root (also runs the api/ module's tests)
make root-test	Unit tests gated on testutil.RequiresRoot
make integration	End-to-end tests in integration/client/ (requires a running daemon)
make cri-integration	CRI integration via script/test/cri-integration.sh
make benchmark	go test -bench across the repo
make check	golangci-lint run (also lint protobufs via make check-protos)
make coverage / make root-coverage	Coverage profiles

For a faster inner loop on a single package: go test ./core/snapshots/... etc.

Smoke testing with ctr

With the daemon running, ctr exercises the gRPC API directly. A few common commands:

ctr version
ctr namespaces ls
ctr images pull docker.io/library/alpine:latest
ctr run --rm docker.io/library/alpine:latest demo /bin/echo hello

ctr is meant for development and debugging only — its UX and CLI are not stable.

Using the Go client

import containerd "github.com/containerd/containerd/v2/client"

c, err := containerd.New("/run/containerd/containerd.sock")
defer c.Close()

ctx := namespaces.WithNamespace(context.Background(), "default")
img, err := c.Pull(ctx, "docker.io/library/alpine:latest", containerd.WithPullUnpack)

The full API surface is documented inline; see client package for the moving parts.

Common build tags

Tag	Effect
no_btrfs	Drop the btrfs snapshotter (drops the C dependency)
no_devmapper	Drop the devmapper snapshotter
no_zfs	Drop the ZFS snapshotter
no_cri	Build without the CRI plugin
no_grpc	Used for the shim build to drop gRPC server code
urfave_cli_no_docs	Strip the urfave/cli docs generator (set by default)

bin/containerd-shim-runc-v2 is built with CGO_ENABLED=0 and no_grpc for a static, gRPC-free shim.