Optimize Docker Container Performance with CPU and Memory Limits

Docker containers do not automatically behave like small virtual machines with fixed resources. Unless you tell Docker otherwise, a container can compete for host CPU and memory like any other process. That is convenient on a laptop and risky on a shared server.

CPU and memory limits are not magic performance boosters. A limit that is too low makes an application slower or unstable. A limit that is too high does not protect the host. The goal is to give each container enough room for normal and peak work while preventing one bad process from taking down everything else on the machine.

Why Limits Matter

The common failure mode is familiar: one container starts a runaway job, memory climbs, the host begins swapping, and unrelated services slow down. Or a CPU-heavy batch task uses every core and the API container beside it starts missing latency targets.

Limits help with three practical problems:

• They protect the host from a single container using all memory.
• They make performance testing more honest because the container runs with production-like constraints.
• They force you to notice when an application needs scaling or tuning instead of silently borrowing resources from neighbors.

Do not start with random numbers. Run the service under load, watch actual usage, and set limits with headroom. A small background worker and a JVM service need very different treatment.

CPU Controls

Docker exposes a few CPU controls. The most useful day to day is --cpus.

Limit a container to roughly one and a half CPUs:

docker run -d --name api --cpus="1.5" nginx

This is easier to read than setting CFS quota and period manually. Under the hood, Docker uses Linux CPU scheduling controls.

--cpu-shares is different. It is a relative weight during CPU contention, not a hard cap:

docker run -d --name important-api --cpu-shares 2048 nginx
docker run -d --name batch-worker --cpu-shares 512 worker-image

When the host has idle CPU, both containers can use more. When they compete, the first container has more scheduling weight. This is useful for prioritization, but it does not stop a container from using spare CPU.

If you need exact CFS settings, --cpu-period and --cpu-quota are still available:

docker run -d --name limited-api \
  --cpu-period 100000 \
  --cpu-quota 50000 \
  nginx

That gives the container 50,000 microseconds of CPU time in each 100,000 microsecond period, roughly half of one CPU. For most teams, --cpus="0.5" communicates the same intent more clearly.

Memory Controls

Memory limits are more dangerous than CPU limits because exceeding them can kill the process. Set them deliberately and test peak behavior.

The basic option is --memory:

docker run -d --name web --memory 512m nginx

If the container exceeds the limit, the kernel may kill a process in the container. In Docker output you will often see this as an OOM kill:

docker inspect web --format '{{.State.OOMKilled}}'

Swap behavior is easy to misunderstand. When --memory is set, --memory-swap is the total memory plus swap allowance, not the swap allowance by itself.

This allows 256 MB of RAM and up to 256 MB of swap, for 512 MB total:

docker run -d --name worker --memory 256m --memory-swap 512m alpine

Setting --memory-swap equal to --memory disables additional swap for that container on systems where swap accounting is available:

docker run -d --name no-extra-swap --memory 256m --memory-swap 256m alpine

Setting --memory-swap -1 allows unlimited swap up to the host's available swap. That may keep a process alive, but it can make latency terrible.

Monitor Before and After

Use docker stats while the service is under realistic load:

docker stats
docker stats web worker

Watch CPU %, MEM USAGE / LIMIT, BLOCK I/O, and PIDS. A service sitting at 100 percent of its memory limit is not "efficient"; it is one traffic spike away from being killed. A CPU-bound service that is constantly throttled may show acceptable average CPU while users see slow requests.

For a quick one-shot view:

docker stats --no-stream

For OOM and restart clues:

docker ps -a
docker inspect <container> --format 'OOM={{.State.OOMKilled}} Exit={{.State.ExitCode}}'
docker logs --tail 100 <container>

For ongoing monitoring, export container metrics to Prometheus, Grafana, a cloud monitoring service, or the platform you already use. docker stats is triage, not a long-term alerting system.

A Sensible Tuning Workflow

Start without tight limits in a test environment and capture idle, normal, and peak usage. Then set memory above observed peak with enough headroom for garbage collection, cache growth, TLS handshakes, and short bursts. For CPU, decide whether you need a hard cap or just relative priority.

Example for a small API:

docker run -d --name api \
  --cpus="2" \
  --memory 1g \
  --memory-swap 1g \
  -p 8080:80 \
  my-api:latest

That says the API gets up to two CPUs, 1 GB of RAM, and no extra swap allowance. It is not universally correct. It is a clear starting point for a service that has been tested near that range.

For Docker Compose, the local Docker engine supports resource options such as:

services:
  api:
    image: my-api:latest
    mem_limit: 1g
    cpus: 2.0

Compose and Swarm/Kubernetes resource settings are not identical, so check the deployment target before assuming a field has the same behavior everywhere.

Common Mistakes

Setting memory too low is the most common mistake. The application starts, passes a smoke test, then dies under a request pattern that allocates more memory than the test covered.

Using CPU limits to hide inefficient code is another. If a service is slow because it is doing expensive work per request, a lower CPU limit makes the symptoms more obvious. It does not fix the code path.

Ignoring language runtimes also hurts. JVM, Node.js, Go, Python, and Ruby apps respond differently to memory pressure. Some runtimes need explicit heap settings so their internal memory assumptions match the container limit.

Finally, do not tune only one container. The host still needs CPU and memory for the kernel, Docker, logging, monitoring agents, and any sidecar processes. Leave room.

Good limits make failure smaller and performance more predictable. They should come from measurement, not guesswork.