Docker Resource Limits

A container shares the host machine with every other container. Without limits, one greedy container can swallow all memory or processing power and slow down everything around it. Resource limits give each container a fair share and protect the host from runaway programs.

The Shared Apartment Analogy

Think of a host machine as an apartment with one kitchen, one power meter, and one water pipe. Each container is a roommate. A roommate who runs every appliance at once leaves the others in the dark. House rules, such as a maximum power budget per person, keep life peaceful.

Host machine: 8 GB RAM, 4 CPU cores

Container A  limit 2 GB, 1 CPU
Container B  limit 1 GB, 0.5 CPU
Container C  limit 512 MB, 0.5 CPU

Limiting Memory

The --memory flag sets the maximum RAM a container may use.

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

Valid units include b, k, m, and g. When a container tries to use more memory than its limit, the kernel stops one of its processes. Docker reports this event as an out-of-memory kill. The container often restarts if you set a restart policy.

Memory Plus Swap

Swap is disk space that acts as slow extra memory. The --memory-swap flag sets the combined limit of RAM and swap.

docker run -d --memory="512m" --memory-swap="1g" nginx

This container can use 512 MB of RAM and 512 MB of swap. Setting both flags to the same value disables swap for the container.

Limiting CPU

The --cpus flag controls how many CPU cores a container may use.

docker run -d --cpus="1.5" my-app

A value of 1.5 means the container can use one and a half cores worth of time. A value of 0.5 means half a core.

CPU Shares

The --cpu-shares flag sets a relative weight. Weights matter only when containers compete for time. A container with weight 1024 gets twice the time of a container with weight 512 during a busy period. During quiet periods every container takes whatever it needs.

docker run -d --cpu-shares=1024 important-app
docker run -d --cpu-shares=512  background-job

Watching Live Usage

The docker stats command shows a live table of resource use.

CONTAINER  CPU %   MEM USAGE / LIMIT    MEM %   NET I/O
web        0.05%   12MiB / 512MiB       2.34%   1.2kB / 0B
api        14.8%   310MiB / 1GiB        30.2%   8.4MB / 2MB

Read the MEM USAGE / LIMIT column to confirm that the limit exists. A limit that shows the full host memory means no limit was set.

Limits in Docker Compose

services:
  api:
    image: my-api
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          memory: 256M

Limits mark the ceiling. Reservations mark the minimum amount the container expects to receive.

Choosing Good Values

1. Run the container without limits in a test environment.
2. Watch docker stats during normal and peak load.
3. Set the memory limit about 25 percent above the peak.
4. Test again and adjust.

A limit set too low causes constant restarts. A limit set too high wastes the protection. Measure first and guess never.

Common Mistakes

• Skipping limits on development machines and discovering problems only in production.
• Setting memory below what the application needs to start, such as Java programs that need several hundred megabytes at launch.
• Forgetting that every container on the host shares the same total pool.

Real-World Scenario

A small company runs a website, an image resizer, and a report generator on one server. During the monthly report run, the generator consumes nearly all memory. The website slows down, and customers complain. The team sets a 1 GB memory limit and a one-core CPU limit on the report generator. The next monthly run finishes a little slower, and the website stays fast the whole time.

The same idea protects against bugs. A memory leak in one container grows until the limit arrives, and Docker stops only that container. Without a limit, the leak would drag the whole server into a crash. Limits turn a server-wide outage into a small, contained event.

Checking for Out-of-Memory Events

docker inspect --format="{{.State.OOMKilled}}" web
true

A true value confirms that the kernel stopped the container for exceeding its memory limit. Raise the limit or fix the leak depending on the cause.