Set Docker resource limits

The fix

docker run \
  --memory=512m \
  --cpus=1.0 \
  --pids-limit=200 \
  --read-only --tmpfs /tmp \
  myimage

services:
  app:
    mem_limit: 512m
    cpus: 1.0
    pids_limit: 200
    read_only: true
    tmpfs: [/tmp]

Why it matters

Containers have no resource limits by default. A container can allocate all the host’s memory, saturate every core, and create processes until the kernel’s PID table is full. Namespaces isolate what a process can see; they do not ration what it can consume.

This closes no exposure and stops no attacker who has code execution — which is why it’s low and last. What it prevents is one container taking down every other container on the box, which is a different problem and a real one.

pids-limit is the one that matters

Of the three, this is the one worth setting even if you skip the others.

Memory and CPU exhaustion are noisy and gradual; the OOM killer eventually intervenes, and a pegged CPU is slow rather than fatal. PID exhaustion is neither. A fork bomb in one container fills the host’s global PID table, and once it’s full the host cannot fork any new process at all — including the shell you’d use to fix it, and including docker itself. Recovery is often a hard reboot.

--pids-limit=200

That’s the whole fix. It costs nothing, breaks essentially nothing (200 processes is generous for a typical service), and turns an unrecoverable host into one container failing.

It doesn’t need to be an attack, either — a buggy loop spawning subprocesses does it just as well.

read-only is cheap and underused

--read-only --tmpfs /tmp

A read-only root filesystem means a compromise can’t drop a payload into the container, can’t rewrite your application code, and can’t persist anything across a restart. --tmpfs /tmp gives back the scratch space most applications need, and it lives in memory rather than on disk.

Most stateless services run read-only with no changes. It’s one of the highest value-to-effort items here, which is why it’s on this page rather than left out — it doesn’t really belong under “resource limits”, but it belongs somewhere and this is the closest fit.

Memory limits have a subtlety

--memory=512m

Without --memory-swap, Docker sets swap to twice the memory limit — so --memory=512m actually permits 512 MB RAM plus 512 MB swap. If you meant “512 MB total, no swap”:

--memory=512m --memory-swap=512m

Setting them equal disables swap for the container. That’s usually what you want for a service where swapping is worse than failing, and it’s not what you get by default.

Verify it worked

Find containers with no limits — expect most of them on a first run:

docker ps -q | xargs -r docker inspect --format \
  '{{.Name}} mem={{.HostConfig.Memory}} cpu={{.HostConfig.NanoCpus}} pids={{.HostConfig.PidsLimit}}'

0 means unlimited in every column. pids=0 is the one to fix first.

See live consumption against limits:

docker stats --no-stream

A MEM USAGE / LIMIT showing the host’s total RAM as the limit means no limit is set.

Confirm read-only is real:

docker exec <container> sh -c 'touch /test-write'

Expect Read-only file system.

And prove the PID limit, safely — this is bounded by the limit itself:

docker run --rm --pids-limit=20 alpine sh -c \
  'for i in $(seq 1 50); do sleep 30 & done; echo "spawned: $(ps | wc -l)"'

It fails to spawn past the limit rather than taking anything down. Do not run that without --pids-limit.

Before you apply this

Memory limits kill containers. When a container hits its --memory ceiling the kernel OOM-kills a process inside it, usually the main one, and the container dies. Docker records it:

docker inspect <container> --format '{{.State.OOMKilled}}'

That’s the signature people miss — a container that “randomly restarts” with exit code 137 is being OOM-killed, not crashing.

Measure before you limit. Watch real usage under real load for a while:

docker stats --no-stream --format '{{.Name}} {{.MemUsage}} {{.CPUPerc}}'

Set the limit above the observed peak with headroom, not at the average. JVM and Node applications are the classic trap: they size their heaps from what they see, and unless configured for cgroup awareness they may see the host’s total RAM and plan to use it — then get killed at your limit. Modern JVMs and Node handle this, older ones need explicit flags.

--read-only breaks anything that writes outside a volume — and that’s more things than you’d expect: pidfiles, unix sockets, cache directories, session files, and framework temp paths. Find them:

docker run --read-only myimage 2>&1 | head

Then add a --tmpfs for each, or a volume if it must persist.

--pids-limit is the safest of the three. 200 is generous for a normal service; a build container or something spawning workers may need more. It fails with “resource temporarily unavailable” on fork, which is at least a diagnosable error — unlike the fork bomb it prevents.

Related

• Drop capabilities — the other per-container narrowing.
• Rootless mode — note cgroup v2 is required there for limits to work at all.