Resource Limits

Sets the maximum number of CPU cores a container can use.

      $ docker run --cpus 2.5 myapp
    

• Container can use at most 2.5 CPU cores
• Maps to cgroup v2: cpu.max = 250000 100000 (250ms quota out of every 100ms period)
• When the quota is exhausted in a period, the container is throttled — processes are paused until the next period
• Container is never killed for exceeding CPU — only throttled

--cpus 2.5 → cpu.max: 250000 100000

--cpus 0.5 → cpu.max: 50000 100000

Relative CPU weight — only matters when CPU is contended.

      $ docker run --cpu-shares 512 myapp
    

• Default: 1024
• A container with 512 shares gets half the CPU time of a container with 1024 shares — only when both are competing for CPU
• When no contention, containers can use all available CPU regardless of shares
• Maps to cgroup v2: cpu.weight (converted from v1 shares scale)

Restrict a container to specific CPU cores.

      $ docker run --cpuset-cpus "0,1" myapp

      $ docker run --cpuset-cpus "0-3" myapp
    

• Container can only execute on the specified cores
• Maps to cgroup: cpuset.cpus
• Use cases: NUMA-aware workloads, latency-sensitive applications, isolating noisy neighbors
• Combine with --cpus for both pinning and bandwidth limiting

--cpuset-cpus "0,1" → cpuset.cpus: 0,1

Maximum memory the container can use. Exceeding it triggers the OOM killer.

      $ docker run --memory 512m myapp
    

• Hard limit — maps to cgroup v2: memory.max = 536870912 (512 * 1024 * 1024)
• When the container exceeds this, the kernel OOM killer kills the container process
• Docker then applies the restart policy to determine whether to restart it
• Suffixes: b, k, m, g

Best-effort limit — only enforced when the host is under memory pressure.

      $ docker run --memory 512m --memory-reservation 256m myapp
    

• Maps to cgroup v2: memory.low
• Under normal conditions, the container can use up to --memory
• Under host memory pressure, the kernel tries to reclaim memory down to the reservation level
• Must be lower than --memory

Controls total memory + swap available to the container.

      $ docker run --memory 512m --memory-swap 1g myapp
    

• --memory-swap 1g --memory 512m = 512m RAM + 512m swap (total = swap value)
• --memory-swap -1 = unlimited swap
• --memory-swap equal to --memory = no swap
• If --memory-swap is not set, swap = 2x memory (default)

      $ docker run --memory 512m --oom-kill-disable myapp
    

• Prevents the OOM killer from killing the container when it exceeds --memory
• The container hangs instead — memory allocations block indefinitely

Important limitation: I/O limits only work with direct I/O (bypassing the page cache, e.g., O_DIRECT). Buffered I/O goes through the page cache and is not subject to these limits. Most applications use buffered I/O by default, so these limits may have little practical effect unless the workload uses direct I/O (e.g., some databases with O_DIRECT enabled).

      $ docker run --pids-limit 100 myapp
    

• Maximum 100 processes (including threads) inside the container
• Maps to cgroup: pids.max = 100
• Primary use case: fork bomb protection
• When the limit is hit, fork() / clone() fails with EAGAIN
• The container is not killed — new process creation is simply denied

Related: For the cgroup internals behind these flags (cpu.max, memory.max, pids.max, io.max), see Virt 03 — cgroup Controllers.

Related: For Kubernetes resource limits (requests, limits, QoS classes) which build on these same cgroup mechanisms, see Virt 03 — cgroups in Practice.