Pumba: container chaos testing for Docker, containerd and Podman

What Pumba is for, and who should run it

Pumba is a command line tool that injects faults into running Linux containers. The README describes it as a chaos testing and network emulation tool for Docker, containerd and Podman, inspired by Netflix Chaos Monkey, and it brings that idea down to the container level: kill, stop, pause and remove containers, add network delay or packet loss, or stress container resources.

The audience is narrow but real. If you run containerised services and want to see how they behave when a dependency disappears, when the network turns slow, or when a neighbour eats the CPU, Pumba gives you a way to produce those conditions on demand. It is aimed at people who already have a container runtime socket within reach and are comfortable running a binary with enough privilege to stop other people's workloads. That last point matters more than the feature list: the same access that makes Pumba useful makes it dangerous in the wrong hands.

How Pumba reaches containers: runtime APIs plus a sidecar

The mechanism has two halves. The CLI talks to a container runtime over its API, listing and filtering containers, then acting on the ones that match. The README's diagram shows the Pumba CLI connecting to the Docker API, the containerd API or the Podman compat API, then listing and filtering target containers before issuing kill, stop, pause or rm.

The second half is network chaos. For netem and iptables work, Pumba does not run tc inside your container. It uses a helper container or direct exec that shares the target's network namespace and runs tc or iptables there. That design is why the runtime matters so much. Docker works as root or with socket access. containerd requires root because of the overlayfs mounts used for the sidecar, and it exposes namespaces k8s.io for Kubernetes, moby for Docker-managed containers and default for pure containerd. Podman requires rootful Podman and, per the README, fails fast otherwise; it goes through Podman's Docker-compatible API, and on macOS Pumba runs inside podman machine.

The targeting layer is where most day-to-day mistakes happen. Containers can be selected by name, by regex with the re2: prefix, by labels, or with --random. The README's own first example, pumba --interval=30s --random kill "re2:^test", shows how easily a pattern and a random pick combine into something that hits more than you intended.

Installing Pumba and running a first netem delay

The README offers two install paths. You can download a release binary for your platform, or you can run the published image, which the README labels as recommended. The binary route uses the latest release asset name directly.

curl -sL https://github.com/alexei-led/pumba/releases/latest/download/pumba_linux_amd64 -o pumba
chmod +x pumba

The container route pulls from GitHub Container Registry:

docker pull ghcr.io/alexei-led/pumba:latest

For a first real use, pick a container you are willing to break and add latency to its egress traffic for a bounded window. The README gives this exact form: a duration of 5m and a 3000 millisecond delay applied to a container named mydb.

pumba netem --duration 5m delay --time 3000 mydb

What you should see is the command holding the delay for the stated duration and then releasing it; the README does not document a rollback command, so the duration flag is what ends the experiment. If you want loss instead of delay, or both at once, the combined form puts them in one owned netem qdisc:

pumba netem --duration 5m combine --delay --delay-time 100 --loss --loss-percent 20 -- mydb

Note the double dash before the container name in that example. It separates the effect flags from the target, and dropping it is an easy way to get an argument parsed as a container name.

Where Pumba stops being the right tool

The most explicit limitation is platform support, and the README is unusually blunt about it. Pumba targets Linux containers because every chaos action depends on Linux primitives: network namespaces, cgroups v2, iptables, tc qdiscs and runtime sockets. Windows is not supported and, in the project's words, not planned. The reasoning given is that POSIX signal forwarding, including SIGCONT, SIGSTOP, SIGUSR1 and SIGUSR2 used by the containerd runtime, has no Windows equivalent, and that even Docker Desktop's WSL2 backend does not create a plausible use case. PRs adding Windows support will not be accepted.

macOS is a subtler case. Binaries are published for darwin on amd64 and arm64, but the README frames them as developer ergonomics only: you use them to drive a remote Docker, Podman or containerd VM such as Colima or podman machine. Running Pumba on a Mac does not give you a Mac chaos tool; it gives you a client for a Linux host.

Privilege is the second boundary. containerd netem and iptables work requires root for the overlayfs mounts the sidecar needs, and Podman requires rootful Podman. If your environment deliberately runs rootless Podman, Pumba is the wrong instrument. There is also a scope limit that the README implies rather than states: Pumba acts on containers it can see through one runtime socket, so a multi-cluster or multi-runtime estate needs a Pumba invocation per socket, and nothing in the README describes coordinating those runs.

Pumba against Kubernetes-native chaos controllers

The obvious alternative for Kubernetes users is a chaos controller that runs inside the cluster, such as the Chaos Mesh family of tools. The difference is architectural rather than a matter of feature counts. A controller installs custom resources and a set of controllers into the cluster, and experiments are declared as objects that the cluster reconciles; the experiment's identity lives in the API server.

Pumba inverts that. It is a CLI or a single container that reaches out to a runtime socket and acts immediately. There is no CRD, no reconciliation loop and no cluster-side state. That makes it trivial to run from a laptop against a remote Docker host, and it makes it a poor fit for anything that needs an audit trail of who ran which experiment when. The README's Kubernetes examples (k8s_delay_demo.sh, k8s_pause_demo.sh, k8s_stress_demo.sh) suggest the intended Kubernetes pattern is driving Pumba against a containerd socket with the k8s.io namespace, not deploying a control plane. If you need per-namespace policy, admission control or a UI, a cluster-native controller is the better shape. If you need a one-line fault injection against a single container on a host you control, Pumba is lighter.

Maintenance, licensing and what upgrades cost

The repository is not archived, and the last push was on 2026-09-17, so the project is being worked on. The recent release history shows 1.1.7 on 2026-05-05, then 1.2.0 and 1.2.1 both on 2026-08-23, which is a normal cadence for a small tool rather than a sign of either neglect or rapid churn.

Pumba is licensed under Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices; it is not a copyleft licence, so it does not reach into your own code. This is a description of the licence text, not legal advice, and if you redistribute a modified Pumba you should read the terms yourself.

Upgrade cost is dominated by the runtime client libraries rather than by Pumba's own surface. The go.mod pins github.com/docker/docker v28.5.2+incompatible, github.com/containerd/containerd/v2 v2.2.5, github.com/containerd/containerd/api v1.10.0 and github.com/opencontainers/runtime-spec v1.3.0. Those are the moving parts that matter when a runtime changes its socket behaviour or its API version. Because Pumba depends on the Docker and containerd clients directly, a runtime upgrade on your hosts can break Pumba before Pumba itself releases anything. The Makefile builds with TARGETOS defaulting to linux and TARGETARCH defaulting to amd64, and carries the comment that Windows is intentionally not built, so the release matrix is deliberate. The practical upgrade check is whether the runtime version you run is one the pinned client libraries understand.

Editorial conclusion

Adopt Pumba if your workloads are Linux containers and you want fault injection that runs from a single binary or image without a cluster-side agent. Do not adopt it if you target Windows containers, or if you need a scheduler that owns the experiment lifecycle across a whole cluster. Before you trust it in a shared environment, verify that the runtime socket you point it at is the one you think it is, and check the targeting filter with a dry run first, because a regex that is broader than intended will kill containers you did not mean to touch.

Frequently asked questions

Official sources

1. alexei-led/pumba on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases