Setting Docker Container Resource Limits

Controlling Container Resource Consumption

By default, Docker containers can use unlimited host resources. The --memory and --cpus flags set upper bounds to prevent a single container from monopolizing the host:

docker run -d \
  --memory 512m \
  --cpus 1.5 \
  --name api \
  my-api-image

This container can use at most 512 MB of RAM and 1.5 CPU cores.

Memory Limits

--memory 256m      # 256 megabytes
--memory 1g        # 1 gigabyte
--memory 2g        # 2 gigabytes

When a container exceeds its memory limit, the Linux OOM (Out of Memory) killer terminates it. Docker reports this as exit code 137 (128 + SIGKILL signal 9).

Memory Reservation (Soft Limit)

docker run -d --memory 1g --memory-reservation 512m my-app

The reservation is a soft limit. Docker tries to keep the container's memory at or below 512 MB under normal conditions but allows bursts up to the hard limit of 1 GB.

CPU Limits

--cpus 0.5         # Half of one CPU core
--cpus 1           # One full CPU core
--cpus 2           # Two CPU cores
--cpus 4           # Four CPU cores

The --cpus flag limits total CPU time. A container with --cpus 1.5 can use the equivalent of 1.5 cores across any number of physical cores.

CPU Shares (Relative Weight)

For relative prioritization rather than hard limits, use --cpu-shares:

docker run -d --cpu-shares 1024 --name high-priority my-app
docker run -d --cpu-shares 512 --name low-priority my-worker

CPU shares only matter when containers compete for CPU time. If the host is idle, even a low-share container gets full CPU access.

Practical Resource Configurations

# Small microservice
docker run -d --memory 256m --cpus 0.5 --name auth-service auth-image

# Medium API server
docker run -d --memory 1g --cpus 2 --name api-server api-image

# Database server
docker run -d --memory 4g --cpus 4 --name database postgres:16

# Background worker
docker run -d --memory 512m --cpus 1 --name worker worker-image

# Memory-intensive processing
docker run --memory 8g --cpus 8 --name batch-job batch-image

Monitoring Resource Usage

# Real-time stats
docker stats

# Stats for a specific container
docker stats my-container

# One-shot (no streaming)
docker stats --no-stream

Swap and Memory Behavior

# Disable swap entirely (recommended for predictable performance)
docker run --memory 512m --memory-swap 512m my-app

# Allow 512m RAM + 512m swap (1g total)
docker run --memory 512m --memory-swap 1g my-app

Setting --memory-swap equal to --memory effectively disables swap for the container, which is recommended for latency-sensitive services.