Before diving into cgroups and kernel internals, it’s worth being precise about what “swappiness” means — and what it doesn’t.

The one-sentence definition

Swappiness is a tunable value, from 0 to 100, that tells the Linux kernel how aggressively it should move memory pages out to swap space rather than reclaiming them from the page cache when the system needs to free up RAM. In Docker, memory swappiness tuning means setting that same behavior on a per-container basis, so one container’s appetite for swapping doesn’t have to match the host’s global default, or any other container’s.

A little history

Swappiness as a concept predates containers entirely — it has been a host-wide Linux kernel tunable for well over two decades, originally added simply so administrators could bias the kernel’s reclaim behavior for a given machine’s workload, long before anyone was running isolated, per-application cgroups. Containers didn’t introduce a new concept here; they simply gave an existing, mature kernel mechanism a narrower, per-workload scope to operate in, which is part of why the underlying reasoning about anonymous versus file-backed pages, covered next, hasn’t changed at all in the container era — only the boundary it’s applied within has.

Swappiness only makes sense once you understand that the kernel treats memory pages as belonging to two very different families, each with its own reclaim story.

Anonymous pages vs. file-backed pages

Every page of memory a process uses falls into one of two broad categories. File-backed pages hold data that also exists on disk somewhere — a program’s executable code, a memory-mapped file, or the page cache holding recently-read file contents. Because a copy already exists on disk, the kernel can reclaim these pages cheaply: it just discards them, and re-reads from disk later if needed. Anonymous pages, by contrast, hold data that has no disk-backed origin at all — a process’s heap, its stack, dynamically allocated memory. There’s no disk copy to fall back on, so the only way to reclaim an anonymous page under pressure is to write it out to swap space first.

Where swappiness fits into this picture

When the kernel needs to free up memory, it has a choice: reclaim file-backed pages (cheap, but might mean re-reading files from disk later, hurting I/O performance) or swap out anonymous pages (writes to swap now, but the anonymous data itself might not be needed again soon). Swappiness is the dial that expresses a preference between these two options. A low value biases the kernel strongly toward reclaiming file-backed page cache first, only swapping anonymous pages as a last resort. A high value tells the kernel to treat anonymous-page swapping as a much more acceptable, earlier option.

Docker doesn’t invent its own memory-management engine. It configures the Linux kernel’s control groups (cgroups) memory subsystem, and simply exposes the relevant settings as friendly CLI flags.

The key virtual files behind the flags

Every container gets its own cgroup — a kernel-managed accounting and limiting boundary — and that cgroup exposes a handful of pseudo-files under the cgroup filesystem that directly control memory behavior. Docker’s CLI flags are, underneath, just writing values into these files on the container’s behalf.

graph TD
    A["Docker CLI flag"] --> B["dockerd"]
    B --> C["containerd / runc"]
    C --> D["cgroup memory subsystem"]
    D --> E["memory.limit_in_bytes"]
    D --> F["memory.memsw.limit_in_bytes"]
    D --> G["memory.swappiness"]
    D --> H["memory.soft_limit_in_bytes"]
    E --> I["Kernel enforces RAM ceiling"]
    F --> J["Kernel enforces RAM+swap ceiling"]
    G --> K["Kernel biases reclaim toward or away from swap"]
        

Per-container, not per-process

Because every process a container spawns lives inside that same cgroup, swappiness (and every other memory limit) applies collectively to the whole container — a container running five processes doesn’t get five independent memory budgets, it gets one shared budget and one shared swappiness value that the kernel applies uniformly to reclaim decisions across all of them.

From Docker command to running container: the translation path

It’s worth naming every layer this setting actually passes through, because troubleshooting often means figuring out which layer dropped or ignored it. A memory-related flag on docker run is first received by the Docker daemon, which translates it into the OCI runtime specification format used to describe how a container should be created. That specification is then handed to a lower-level container runtime, which is responsible for actually creating the cgroup and writing the appropriate values into its memory-control files before the container’s process is started inside it. Each of these layers is a place where a mismatch — an unsupported flag on a given kernel version, a runtime that doesn’t propagate a particular field — can silently prevent a setting from having the effect its name suggests.

Swap accounting must be enabled for any of this to work at all

On cgroup v1 systems in particular, tracking and limiting swap usage per cgroup is an optional kernel feature called swap accounting, and it has historically needed to be explicitly enabled — sometimes via a kernel boot parameter — before the memory-and-swap combined limit becomes meaningful at all. On a host where swap accounting isn’t enabled, Docker may still accept a --memory-swap value without error, but the kernel has no way to actually enforce a separate swap ceiling, which can be a confusing gap between configured intent and real enforcement.

Swappiness isn’t a simple on/off switch — it’s an input to a scoring algorithm the kernel runs whenever it needs to free memory. Understanding that algorithm, at least conceptually, demystifies why the number 0–100 behaves the way it does.

The LRU lists

The kernel tracks memory pages using Least-Recently-Used (LRU) lists — separate lists for anonymous pages and for file-backed pages, each roughly ordered from “recently used” to “not used in a while.” When memory needs to be freed, the kernel doesn’t reclaim randomly; it scans from the “not recently used” end of these lists, preferring pages that haven’t been touched in a while, on the theory that they’re least likely to be needed again soon.

How swappiness weights the scan

Rather than scanning only one list or the other, the kernel calculates a ratio of how much scanning effort to spend on the anonymous LRU list versus the file-backed LRU list, and swappiness is a direct input to that ratio. A low swappiness value skews the ratio heavily toward scanning (and reclaiming) file-backed pages, leaving anonymous pages alone unless there’s truly nothing else left to reclaim. A high swappiness value flattens that skew, making the kernel willing to scan and swap out anonymous pages proportionally much earlier, even while reclaimable file-backed pages still exist.

sequenceDiagram
    participant K as Kernel memory manager
    participant F as File-backed LRU list
    participant A as Anonymous LRU list
    participant S as Swap space
    K->>K: Memory pressure detected in cgroup
    K->>K: Compute scan ratio from swappiness value
    K->>F: Scan and reclaim cold file-backed pages
    alt Still need more memory
        K->>A: Scan cold anonymous pages
        A->>S: Write selected pages out to swap
    end
    Note over K: Higher swappiness shifts this ratio toward the Anonymous path sooner
        

Pressure is relative to the cgroup, not just the host

Under cgroup-enforced memory limits, this whole reclaim dance can be triggered purely by a single container approaching its own memory limit, even while the host machine as a whole has plenty of free RAM sitting idle. This is a frequent source of confusion: a container can be swapping heavily, or even get OOM-killed, on a host that free -m shows as mostly empty — because the constraint that matters is the container’s cgroup boundary, not the host’s total capacity.

What happens when a swapped page is needed again

Swapping a page out is only half the story — eventually, the process that owned it may try to access that memory again. When that happens, the CPU generates what’s called a page fault: the process’s execution pauses momentarily, the kernel notices the page it needs is out on swap rather than in RAM, and it reads that page back in from swap before letting the process continue. This round trip is exactly where the latency cost of swapping becomes visible to an application — a memory access that would normally take nanoseconds can instead take the time of an actual disk read, which is orders of magnitude slower even on fast SSD-backed swap.

Background reclaim vs. direct reclaim

The kernel actually has two modes for this process. A background kernel thread periodically wakes up and proactively reclaims memory while a cgroup is still comfortably under pressure, trying to stay ahead of demand. If allocation requests outpace that background work and memory becomes critically tight, the kernel falls back to direct reclaim — pausing the requesting process itself to free memory synchronously, right there, before it’s allowed to continue. Direct reclaim is considerably more disruptive to an application’s latency than background reclaim, and a well-chosen swappiness value, combined with adequate headroom in the memory limit, is part of what keeps a workload operating in the gentler, background-reclaim regime rather than repeatedly triggering the disruptive one.

Tracing memory pressure from a container’s launch to a potential out-of-memory event shows exactly when swappiness enters the picture, and when it’s bypassed entirely.

Swappiness rarely gets tuned in isolation — it’s usually set alongside a handful of sibling flags that define the container’s overall memory envelope. Understanding how they interact is essential before touching any of them.

Why “swap equals memory” is the most common configuration

A very common production pattern is setting --memory-swap to the exact same value as --memory. Because the combined ceiling then equals the RAM ceiling exactly, there’s no headroom left for swap at all — the container simply cannot swap, no matter what its swappiness value says, because there’s zero swap allowance to write into. In this configuration, swappiness becomes irrelevant; it’s the swap allowance, not the swappiness dial, doing the real work of disabling swap.

The same settings in Compose and orchestrated deployments

Outside of direct docker run invocations, these same underlying limits are typically expressed through a service definition’s resource block in tools like Docker Compose, or through equivalent resource-request fields in higher-level orchestrators. The names and syntax differ across tools, but every one of them is ultimately configuring the same cgroup memory subsystem described in this tutorial — which is exactly why understanding the underlying mechanism pays off regardless of which specific tool or YAML schema a team happens to be using on top of it.

How memory-reservation behaves differently from a hard limit

It’s easy to initially confuse --memory-reservation with --memory, since both look like memory ceilings. The difference is enforcement strength: --memory is a hard boundary the container’s cgroup is never allowed to exceed, full stop. --memory-reservation is a softer target that only gets actively enforced when the host itself is under broader memory pressure — a container can legitimately exceed its reservation during a normal spike, and only gets nudged back toward it if the host as a whole needs the memory back for other workloads.

This is one of the most important — and most frequently missed — practical details in the entire topic, and it changes depending on which cgroup version a host is running.

What changed between versions

Docker’s --memory-swappiness flag was designed against the original cgroup v1 memory subsystem, which exposed a per-cgroup memory.swappiness file that could be tuned independently of the host’s global setting. When the kernel and major Linux distributions moved to cgroup v2, that per-cgroup swappiness control was not carried over in the same form — cgroup v2’s memory controller does not expose an equivalent per-cgroup swappiness setting in the way v1 did.

What this means for tuning strategy

On cgroup v2 hosts, achieving meaningfully different swap behavior between containers generally has to happen through the swap allowance (via --memory-swap) rather than through swappiness itself, since the finer-grained per-container dial isn’t available in the same form. This is a good example of why understanding the underlying mechanism matters more than memorizing a flag — the flag’s real-world effect depends on infrastructure details that aren’t visible from the Docker command line alone.

Figuring out which version a host is actually running

Because so much of this chapter hinges on cgroup version, it’s worth knowing that this isn’t something Docker hides deliberately — it’s simply a property of how the host’s Linux distribution and kernel were configured, generally as part of the base OS setup rather than anything Docker-specific. Most current mainstream Linux distributions have defaulted to cgroup v2 for some time now, while older or more conservatively-configured hosts, and some specialized environments, may still run cgroup v1. When in doubt, checking the host’s cgroup configuration directly — rather than assuming based on distribution age alone — is the reliable way to know which behavior to expect before spending time tuning a flag that might not apply.

Swappiness tuning is ultimately about buying time and shaping behavior before this final mechanism ever has to act — so it’s worth understanding on its own terms.

How the kernel chooses a victim

When a cgroup genuinely runs out of both reclaimable memory and available swap, the kernel’s out-of-memory (OOM) killer selects a process to terminate in order to free memory immediately. Within a container’s cgroup, this selection is typically based on an internal “badness” score influenced by how much memory each process is using, among other factors — the intent is to kill the process that will free the most memory for the least overall disruption, though in a single-process container, there’s often only one realistic candidate.

Container-scoped, not host-scoped

Crucially, this OOM event happens within the container’s own cgroup boundary when a per-container memory limit is set — the host can be sitting on gigabytes of free RAM while one specific, tightly-limited container gets a process killed purely because it exceeded its own individual ceiling. This is precisely the behavior that makes per-container memory and swap tuning meaningful in the first place: it isolates one workload’s memory misbehavior from affecting its neighbors.

Why single-process containers make this predictable

Most containers, by convention, run a single primary application process rather than the many competing processes a traditional multi-user host would have. This actually simplifies OOM behavior in practice: rather than the kernel weighing many candidate processes with different badness scores against each other, an OOM event inside a typical container usually means that container’s one main process is the one being terminated, and the container as a whole exits as a direct result. This predictability is part of why container orchestration systems can build reliable restart-on-failure behavior around OOM events — the failure mode is comparatively simple and consistent compared to a shared, multi-tenant host without this isolation.

There is no universally “correct” swappiness value — only a trade-off that should be matched deliberately to a workload’s actual tolerance for latency versus its tolerance for being killed under pressure.

Framing it as a spectrum, not a binary choice

Because swappiness is a full 0–100 range rather than an on/off switch, the practical tuning exercise for most teams is finding a middle value appropriate to a specific workload’s tolerance, rather than reflexively setting it to one extreme. A background batch-processing container that can tolerate occasional slow page faults is a very different case from a low-latency API server where even rare, brief stalls violate a service-level target — the “right” value genuinely differs between them.

Swap medium matters too

The severity of the latency trade-off described above depends heavily on what the swap space physically sits on. Swap backed by a fast NVMe SSD imposes a far smaller penalty per page fault than swap backed by a spinning hard disk or a slow network-attached volume — the same swappiness value can therefore produce meaningfully different real-world latency impact depending purely on the underlying hardware a host’s swap space lives on. This is worth checking before drawing conclusions from a benchmark run on different hardware than production actually uses.

Swap and memory-limit tuning aren’t purely performance topics — a few real security implications are easy to overlook.

Swappiness misconfiguration tends to show up as one of two symptoms: unexplained latency spikes, or containers dying with no obvious application-level cause. Both have a predictable, small set of places to look, and building the habit of checking them together — rather than any single metric in isolation — is what actually turns this from guesswork into a repeatable diagnostic process.

Building a habit around these signals

None of these individual metrics is meaningful in isolation — a container showing nonzero swap usage isn’t automatically a problem, and a container with zero swap usage isn’t automatically well-tuned either. The useful practice is correlating swap activity with application-level latency metrics over the same time window: if swap usage rises and request latency rises in step, that’s a strong, concrete signal that swappiness (or the surrounding memory limits) genuinely need attention, rather than a change made on instinct alone.

Most swappiness-related incidents trace back to a small number of recurring misunderstandings about how the setting interacts with its sibling limits.

Good pattern: matching memory-reservation to expected steady-state usage

Setting --memory-reservation to a value close to a container’s expected normal memory footprint — below the hard --memory ceiling — gives the kernel a soft target to lean toward reclaiming back to under general host memory pressure, without imposing a hard cap the container can never legitimately exceed for a brief, real spike.

A practical checklist distilled from everything covered so far.

Memory swappiness tuning shows up across a range of real deployment contexts, each with a slightly different rationale.

Pulling the previous chapters together into a repeatable way of reasoning about a new workload, without prescribing a single “correct” number.

Swappiness tuning happens at the operating-system level, but many modern applications also manage their own memory internally — and the two layers don’t always agree on what “important” memory looks like.

Two independent memory managers, working blind to each other

A database or cache application typically maintains its own internal notion of “hot” data — a buffer pool, an in-process cache, frequently-accessed index structures — and decides for itself what to keep readily available versus what to evict or spill elsewhere. The Linux kernel’s reclaim algorithm, meanwhile, has no visibility into that application-level logic at all; it only sees raw memory pages and how recently the CPU has touched them. This means the kernel can, in principle, swap out exactly the pages an application considers its most critical, hot data, simply because the kernel’s own recency signal doesn’t align with the application’s own sense of importance.

Why this matters for swappiness choices

For applications that already do sophisticated internal memory management — many production databases fall into this category — it’s often preferable to keep the operating system’s own swapping behavior as conservative as possible (a low swappiness value, or swap disabled outright), and let the application’s own internal logic be the primary decision-maker about what stays resident. Layering an aggressive OS-level swappiness setting on top of an application that already manages its own memory carefully tends to fight against that application’s own tuning rather than complement it.

No. It makes the kernel avoid swapping anonymous pages as long as possible, but under severe enough pressure the kernel may still swap as a last resort, provided the container has any swap allowance available at all.

Set --memory-swap equal to --memory. This removes any swap headroom at all, which is a more direct and reliable guarantee than relying on swappiness alone.

The host is very likely running cgroup v2, where Docker’s per-container swappiness flag is generally unsupported, and the host’s global swappiness setting governs behavior instead.

Not universally — it depends on the workload. For latency-critical services it’s usually undesirable, but for workloads that can tolerate occasional stalls in exchange for more headroom before an OOM kill, a higher value can be a reasonable, deliberate trade-off.

No. Swappiness only influences behavior on the way toward the memory and swap limits; once those limits are genuinely exhausted, the OOM killer activates regardless of the swappiness setting.

Not necessarily — different workloads have different latency and memory-spike tolerances, and treating swappiness as a per-service decision usually produces better outcomes than a single uniform value applied everywhere.

Yes — a container’s swap activity is real, host-level swap usage under the hood; the cgroup boundary controls and accounts for it, but the underlying swap space itself is a shared host resource.

It’s a reasonable and common choice specifically to prevent sensitive in-memory data from being written to disk, though it does trade away the extra headroom swap would otherwise provide before an OOM event — a deliberate security-versus-resilience trade-off rather than a universally “safest” default.

Often, largely — if an application already manages its own memory carefully relative to the container’s limit, OS-level swappiness becomes a secondary, backstop concern rather than the primary tool for controlling that application’s behavior.

Yes — the latency penalty of a page fault against swap depends heavily on whether swap sits on fast SSD storage or slower media, so the same swappiness value can be far more or less costly depending purely on the underlying hardware.

Memory swappiness tuning is, at its core, a single question repeated at kernel scale millions of times a second: when memory runs low, which kind of page gets reclaimed first — the kind that can be cheaply discarded, or the kind that has to be carried out to slower disk-backed swap space? Docker exposes this same decision on a per-container basis by writing into the cgroup memory subsystem’s files, but the real behavior always depends on the surrounding memory and swap limits, and on which cgroup version the host is actually running. Tuned thoughtfully and matched to a workload’s genuine latency tolerance, swappiness is a quiet but meaningful lever between predictable performance and predictable resilience. It is, deliberately, a small piece of a much larger picture — memory limits, swap allowances, application-level memory management, and monitoring all have to be reasoned about together, and no single flag substitutes for understanding how they interact.