containernetworking/cni: the spec and Go library behind pluggable Linux container networking

What containernetworking/cni solves, and who it is written for

Linux containers need a network interface, an address, routes, and a clean removal of all of that when the container goes away. The README states that CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted. That narrow scope is the point: the specification stays small enough to implement in other languages, and the README argues that a common interface avoids every runtime and orchestrator solving the same pluggable-network problem separately.

The audience is therefore not cluster operators. It is people building a container runtime or a network plugin. The README lists Kubernetes, OpenShift, Cloud Foundry, Apache Mesos, Amazon ECS, Singularity and OpenSVC as runtimes that use CNI, and names Calico, Cilium, Multus, Antrea, Azure CNI, Kube-OVN and many others as third-party plugins. If you are choosing a network for a cluster, you are choosing among those plugins, not this repository. If you are writing the layer that calls a plugin, this repository is your contract.

What is actually inside the repository: SPEC.md, libcni, cnitool, plugins

Four top-level entries carry the weight. SPEC.md is the interface definition. libcni is the Go library for integrating CNI into applications. cnitool is the example command-line tool for executing CNI plugins. plugins/ exists in the tree, but the README points to a separate repository, containernetworking/plugins, for the reference plugins and for a template for making new plugins.

That split matters when you evaluate the project. The library and the specification are versioned here; the concrete implementations of bridge, host-local IPAM and the rest are not. The go.mod shows a small dependency set for a project of this reach: cobra for the CLI, vishvananda/netns for network namespaces, and OpenTelemetry for tracing, with ginkgo and gomega for tests. The presence of otel/trace suggests plugin invocations can be traced, which is useful when a runtime needs to attribute time spent in a plugin.

A CNI operation is a request from the runtime to a plugin binary, not a long-running daemon in the spec itself. The README describes the repository as a specification and libraries for writing plugins to configure network interfaces in Linux containers. The runtime owns the container lifecycle; the plugin owns the interface configuration for that moment.

Building cnitool and where the plugins come from

The README gives no install steps for cnitool, and the repository has no tagged binary distribution described in the README. What it does give is the source location: cnitool/ in this repository, built from Go. The module is github.com/containernetworking/cni and go.mod declares go 1.21, so a Go toolchain at that level or newer is the baseline. The README does not document a prebuilt download, so building from source is the route it leaves open.

cnitool does not implement networking itself. It executes plugins, so you need at least one plugin binary on disk. The README directs you to the separate containernetworking/plugins repository for the reference plugins. Until a plugin such as bridge is built and placed where the tool expects it, cnitool has nothing to invoke, and the README does not spell out that placement path.

A CNI operation is a request from the runtime to a plugin binary, not a long-running daemon in the spec itself. The README describes the repository as a specification and libraries for writing plugins to configure network interfaces in Linux containers. The runtime owns the container lifecycle; the plugin owns the interface configuration for that moment. That is why cnitool is described as an example tool rather than a production component: it exists to exercise the interface, not to manage a cluster.

The specification is the product, and that is also the limitation

CNI's stated advantage is focus. Focus is also why it will be the wrong tool for some readers. If you want a network policy engine, service load balancing, encryption between nodes, or observability of flows, none of that is in this repository. The README lists Calico, Cilium, Antrea and others as the plugins that add those capabilities. The specification covers connectivity and resource removal, and the README is explicit that this is the whole remit.

A second limitation is the repository split. Documentation, examples and issue history for the plugins you will actually run live in containernetworking/plugins, not here. A bug in how a bridge is created is not a bug in this repository. That separation is deliberate, but it means a reader searching for a CNI tutorial will often land here and find a specification and a library instead of a working network.

Third, the interface is Linux-container oriented. The README describes configuring network interfaces in Linux containers, and the library depends on netns for namespace handling. Windows container networking appears in the README only in the context of third-party plugins such as ovn-kubernetes, which states support for both Linux and Windows. Do not read that as CNI providing Windows support from this repository.

How CNI relates to Cilium, Calico and the other plugins people search for

Searches for Cilium CNI and Calico CNI land on plugin projects, not on this one, and the difference in approach is worth stating plainly. CNI defines the call the runtime makes and the shape of the configuration and result. Cilium builds on eBPF and XDP for containers, according to the README's own description, and Calico is described there as a layer 3 virtual network. Both implement the CNI interface; neither is the interface.

Choosing between them is a decision about dataplane, policy model and operational tooling. Choosing CNI is a decision about the contract your runtime speaks. They are not alternatives at the same layer. A runtime that implements CNI can invoke Cilium, Calico, Multus or a plugin you wrote yourself, and Multus is described in the README as a multi plugin, meaning it composes other plugins rather than replacing the interface.

The practical consequence: if your question is which plugin to run in production, this repository answers only the part about how the plugin gets called. The rest of the answer is in the plugin's own documentation.

Releases, maintenance and the cost of tracking the specification

The last push to the default branch was on 2026-09-14, and the most recent release listed is v1.3.1 on 2026-09-03, following v1.3.0 in April 2025 and libcni v1.2.3 in July 2024. The repository is not archived. The cadence suggests the specification and library move deliberately rather than continuously, which fits a project whose value is stability of an interface that many runtimes and plugins depend on.

Upgrade cost concentrates in libcni consumers. If you embed the library, a version bump is a code change in your runtime, and the Go module path github.com/containernetworking/cni is what you pin. If you only implement the specification in another language, you track SPEC.md instead and the release notes are the signal for interface changes. The repository ships a Makefile that includes mk/lint.mk, and the tree carries .golangci.yml and .yamllint.yaml, so contributions are expected to pass lint before merge.

Licensing is Apache-2.0. That is a permissive licence with an explicit patent grant, which is generally the reason runtimes and vendors are willing to embed libcni and implement the spec. This is a description of the licence identifier in the repository, not legal advice; if you redistribute a modified library, read the LICENSE file itself.

Editorial conclusion

Adopt this repository if you are writing a container runtime or a network plugin and need the specification, libcni and the cnitool CLI as your integration surface; the last push was on 2026-09-14 and the latest release is v1.3.1. Do not adopt it expecting a working cluster network, because the reference plugins live in a separate repository and CNI itself only handles connectivity plus resource cleanup on container deletion. Before committing, read SPEC.md end to end and confirm which plugin repository your runtime actually invokes.

Frequently asked questions

Official sources

1. containernetworking/cni on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases