Interpret Docker memory-swap together with the memory limit

The swap setting is not simply a second independent RAM allowance.

Source facts

Docker documents --memory-swap as a combined memory-and-swap allowance when used with --memory. Setting both to the same positive value prevents container swap use. A value of -1 permits swap up to what the host provides. Docker also warns that tools such as free inside a container report host swap rather than the container’s actual permitted swap.

Source: Docker documentation — Resource constraints.

Applicability

Review Docker memory/swap settings as a pair and compare them with the host’s available swap.

DSE recommendation

DSE recommends recording the intended RAM boundary and permitted swap behavior as a pair. Consider latency sensitivity as well as survival under memory pressure; a workload that keeps running while swapping may still fail its service objective. Keep host capacity and other containers in the review. Do not infer enforcement from a familiar command’s output inside the container. Preserve OOM and pressure evidence before increasing limits so a larger allowance does not hide an application growth problem or shift the failure to the host.

Verification

On an isolated host with representative test load, inspect the effective container configuration and relevant host accounting. Confirm that the chosen settings produce the intended swap boundary. Observe latency, memory pressure, and termination evidence together, then document the measured basis for the production values. Retain the two configured values and the host observation with the trial’s load profile. Have the application owner approve the observed response time as well as survival under pressure before changing a production allowance.

Official reference

Docker documentation — Resource constraints. Reviewed October 20, 2026.