Setting Docker Resource Limits

What this article covers

• Why limits matter.
• How to restrict CPU and RAM.
• The difference between limits and reservations.
• Special cases like the OOM killer and swap.
• Practical examples in Compose.

Introduction: Setting Docker resource limits

Docker containers share the host’s resources. Without limits, a single container can consume all CPU, all RAM, or saturate disk I/O, leaving other services slow, causing out-of-memory errors, or even crashing the host. Resource limits ensure each container gets only what it needs while keeping the rest of the system stable.

This article shows how to set CPU, RAM, and I/O limits in Docker and Compose.

Key terms

• cgroups: Linux control groups for resource management.
• OOM: Out of memory.
• Swap: Page file or swap space.
• limits: Maximum resource allocation.
• reservations: Reserved resources.
• shares: CPU prioritization.
• cpus: Maximum CPU time.
• mem_limit: Maximum RAM.

Why set limits?

• Host stability.
• Fair resource allocation.
• Predictable capacity planning.
• Protection against broken applications.
• Better cost control in the cloud.

CPU limit

In compose.yaml:

services:
  app:
    image: mein-app
    deploy:
      resources:
        limits:
          cpus: '1.5'

This restricts the container to 1.5 CPU cores.

RAM limit

services:
  app:
    image: mein-app
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 128M

reservations tells Docker to reserve 128 MB, while limits caps usage at 512 MB.

CPU and RAM combined

services:
  app:
    image: mein-app
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 256M

docker run

docker run -d --name app --memory=512m --cpus=1.5 mein-app

Swap limits

docker run -d --name app --memory=512m --memory-swap=1g mein-app

--memory-swap is the total of RAM plus swap. Setting --memory-swap=512m disables swap.

OOM killer

When a container exceeds its RAM limit, the kernel terminates it. Docker restarts the container based on the restart policy. If OOM errors persist, you need to increase the limit or fix the bug in your application.

CPU shares

For soft prioritization:

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1'
        reservations:
          cpus: '0.2'

Hard limits set with cpus take precedence.

PID limits

docker run --pids-limit=1000 mein-app

Protects against fork bombs.

I/O limits

docker run --device-read-bps /dev/sda:10mb --device-write-bps /dev/sda:10mb mein-app

In Compose, use blkio_config for these options.

Swarm deployments

In Swarm, limits and reservations are critical for scheduling:

deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M
    reservations:
      cpus: '0.5'
      memory: 256M

Swarm only places containers on nodes with sufficient reserved resources.

Tips

• Test limits thoroughly.
• Don’t set them too tight.
• Keep reservations conservative.
• Monitor OOM events.
• Disable swap for latency-sensitive containers.
• Use CPU shares for soft prioritization, hard limits for absolute caps.

Common pitfalls

• Limits too tight: Container crashes with OOM.
• No reservations: Swarm places containers poorly.
• Swap overlooked: Slow performance due to paging.
• Wrong units: 1G vs. 1024M.
• Kernel cgroups: Older cgroups v1 can interpret some options differently.

Further reading and resources

• BotServ.de Docker Container Restarts
• BotServ.de Docker Monitoring
• BotServ.de Docker Security
• BotServ.de Docker Swarm

FAQ: Docker resource limits

What is the difference between limits and reservations? limits sets a hard cap on resource usage, while reservations reserves resources for Swarm scheduling and planning.

What happens on OOM? The container is terminated and restarted according to the restart policy.

Should I disable swap? Yes, for applications that cannot tolerate delays or latency.

Can I limit GPU memory? Not with standard Docker tools. NVIDIA MIG allows GPU partitioning.

Are limits available with docker run? Yes, using --cpus, --memory, and other flags.

Sources and further reading

• Docker Resource Constraints: https://docs.docker.com/config/containers/resource_constraints/
• Compose Resources: https://docs.docker.com/compose/compose-file/05-services/#resources
• cgroups: https://docs.kernel.org/admin-guide/cgroup-v2.html

Summary: Setting Docker resource limits

Resource limits protect Docker hosts from excessive consumption and ensure fair allocation. CPU, RAM, and optionally I/O can all be constrained. In Compose, use deploy.resources; with docker run, use --cpus and --memory. Set limits realistically, use reservations in Swarm, and account for swap to achieve a stable, predictable container environment.