How to Set Docker Resource Limits for RAM and CPU

Stop letting a single buggy container crash your entire host machine.

In a perfect world, every container behaves, stays within its lane, and uses exactly the resources it needs. In the real world, a memory leak in a Python script or an infinite loop in a background worker can trigger an "out-of-memory" (OOM) event, freezing your server and taking every other service down with it.

This is where Docker resource limits come in. By defining hard and soft limits, you can ensure your applications remain stable and your host remains responsive.

The Architecture: Control Groups (cgroups)

Before diving into the commands, it is important to understand how Docker actually enforces these limits. Docker doesn't "simulate" resource restrictions; it leverages a Linux kernel feature called Control Groups (cgroups).

Cgroups allow the OS to partition resources (CPU, memory, disk I/O, network) and assign those partitions to specific processes. When you set a limit in Docker, you are essentially telling the Linux kernel: "Do not let this group of processes exceed X amount of RAM or Y percentage of CPU."

Controlling Memory Usage

Memory is a "non-compressible" resource. If a process asks for more RAM than is available and the system can't provide it, the kernel has no choice but to kill the process to save the system.

Hard Limits (The Ceiling)

A hard limit is the absolute maximum amount of memory a container can use. If the container attempts to exceed this limit, the Linux kernel will trigger an OOM (Out of Memory) Kill, instantly terminating the process inside the container.

docker run -m 512m nginx

In this example, the Nginx container is capped at 512MB. If it hits 513MB, it's gone.

Soft Limits (The Reservation)

Soft limits allow you to guarantee a minimum amount of memory. When the host has plenty of RAM, the container can exceed its soft limit. However, if the host starts running low on memory, Docker forces the container back down to its soft limit.

docker run --memory-reservation 256m nginx

Memory Swap

By default, if you set a memory limit, Docker allows the container to use an equal amount of swap space on the disk. To disable swap or limit it strictly, use the --memory-swap flag.

# Limit RAM to 512MB and total (RAM + Swap) to 512MB (disabling swap)
docker run -m 512m --memory-swap 512m nginx

Controlling CPU Usage

Unlike memory, CPU is a "compressible" resource. If a container hits its CPU limit, the kernel doesn't kill it; it simply "throttles" it, slowing down the execution of the code.

CPU Shares (Relative Weight)

CPU shares define the priority of a container relative to others. This is a weighted system rather than a hard cap. If two containers both want 100% of the CPU, but Container A has 1024 shares and Container B has 512, Container A will get twice as much CPU time.

docker run --cpu-shares 512 nginx

CPU Quotas (Hard Limits)

If you need to ensure a container never uses more than a specific amount of processing power, use --cpus. This is the most intuitive way to limit CPU.

# Limit the container to use a maximum of 1.5 CPUs
docker run --cpus="1.5" nginx

If your machine has 4 cores, this container can use 100% of one core and 50% of another.

Implementing Limits in Docker Compose

Running long strings of flags in the CLI is tedious. In production, you’ll likely use Docker Compose. Since version 3, resource limits are defined under the deploy key.

services:
  web_app:
    image: my-python-app:latest
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M

Note: For docker-compose up to respect these limits in older versions, you may need to use the --compatibility flag.

Summary Table: Quick Reference

Pro Tip: Monitoring Your Limits

Setting limits is only half the battle; you need to know if your limits are too tight. You can monitor real-time resource usage for all running containers with a single command:

docker stats

If you see your memory usage hovering at 99% of your limit, it's time to scale up your resources before the kernel decides to kill your application.