CPU Pinning and CPUSets: Taking Control of Where Your Containers Actually Run
By default, Docker lets the Linux kernel scheduler freely bounce a container's processes between any CPU core on the machine — CPU pinning takes that decision away from the scheduler and nails specific containers to specific cores, unlocking predictable, low-latency performance for workloads that need it.
Picture a busy open-plan office with fifty desks and no assigned seating — every morning, employees just sit wherever there happens to be a free desk. Most days this works fine, but for a handful of specialists who rely on a very specific, carefully calibrated workstation setup, being shuffled to a different desk every day destroys their focus and slows them down. CPU pinning is the equivalent of giving those specialists a permanently reserved desk — no one else sits there, and they never have to pack up, relocate, and re-settle in the middle of important work. In Docker, that “desk” is a physical CPU core, and pinning a container to it means the container’s processes always run there, and nowhere else.
1What Is CPU Pinning?
Let’s start with the foundational idea before layering in Docker-specific mechanics.
The Default Behavior: Free-Floating Scheduling
On a normal Linux system, the kernel’s CPU scheduler is responsible for deciding, many times per second, which process runs on which CPU core. By default, it’s free to move any process — including everything running inside a container — from core to core as it sees fit, based on load balancing, core availability, and other system-wide factors. Most of the time, this is exactly what you want: it keeps the whole system efficiently utilized without anyone having to micromanage it.
CPU Pinning: Restricting a Process to Specific Cores
CPU pinning, also called CPU affinity, is the practice of explicitly telling the kernel “this particular process is only allowed to run on these specific CPU cores — never move it anywhere else.” Once pinned, a process’s execution is restricted to that fixed set of cores for its entire lifetime, regardless of what else is happening on the rest of the machine.
CPUSets: How Docker Implements Pinning
Docker doesn’t invent its own CPU pinning mechanism from scratch — it uses a Linux kernel feature called cpusets, part of the larger control groups (cgroups) system that Docker already relies on for resource management. A cpuset defines exactly which CPU cores (and, for multi-socket machines, which memory nodes) a group of processes is permitted to use. When you configure CPU pinning for a container, Docker is really just creating a cpuset cgroup for that container and restricting it to the cores you specify.
Imagine a hospital scheduling operating rooms. Under normal scheduling, any surgical team could be assigned to any available operating room on any given day — flexible, but it means a team might have to set up their specialized equipment fresh each time in an unfamiliar room. CPU pinning is like permanently reserving Operating Room 3 for the cardiac team alone — their equipment stays exactly where they left it, nothing else interferes with that room, and there’s zero setup delay caused by sharing the space with unrelated teams.
CPU Affinity
The general concept of restricting a process to run only on a specific set of CPU cores.
cpuset cgroup
The Linux kernel control group subsystem Docker uses to enforce which cores and memory nodes a container’s processes may use.
Context Switch
The overhead the CPU incurs when it stops running one process and starts running another, including saving and restoring that process’s state.
CPU Cache Locality
The performance benefit a process gets from repeatedly running on the same core, where its frequently-used data is already sitting in that core’s fast local cache.
2Architecture: Where CPUSets Sit in Docker’s Resource Model
CPU pinning doesn’t operate in isolation — it’s one piece of Docker’s broader cgroup-based resource control system.
graph TD
A[Linux Kernel cgroups] --> B[cpu subsystem - controls CPU time share]
A --> C[cpuset subsystem - controls which cores are usable]
A --> D[memory subsystem - controls RAM limits]
C --> E[Container 1 - pinned to cores 0-1]
C --> F[Container 2 - pinned to cores 2-3]
C --> G[Unpinned containers - free to use any remaining core]
style A fill:#fafafa,stroke:#171717
style C fill:#fef2f2,stroke:#dc2626
style E fill:#fafafa,stroke:#171717
style F fill:#fafafa,stroke:#171717
style G fill:#fafafa,stroke:#171717
CPU Shares vs. CPU Pinning — Two Different Tools
It’s important not to confuse CPU pinning with Docker’s CPU share or quota settings. CPU shares and quotas control how much CPU time a container is entitled to relative to others, but still let the scheduler freely choose which cores to use. CPU pinning, by contrast, controls which specific cores a container is allowed to use at all, regardless of how much total CPU time it consumes. The two mechanisms are complementary — you can pin a container to specific cores and also limit how much of those cores’ time it’s entitled to.
CPU Shares
A relative weighting that determines how CPU time is divided among containers when there’s contention, without restricting which cores are used.
CPU Quota / Period
A hard limit on the absolute amount of CPU time a container can consume within a given time window, again without restricting which cores.
CPUSets (Pinning)
Restricts exactly which physical cores a container’s processes are permitted to execute on, independent of how much time it uses.
NUMA Node Binding
An extension of cpusets on multi-socket machines that also restricts which memory node a container’s processes access, keeping memory access local to the pinned cores.
3Internal Working: How the Kernel Enforces Pinning
Understanding what happens at the kernel scheduler level clarifies exactly why pinning changes performance the way it does.
The Scheduler’s Normal Decision Process
Under normal, unpinned conditions, every time the kernel scheduler needs to decide where to run a process, it considers all cores that process is theoretically allowed to use — which, by default, is every core on the machine. It picks based on factors like current load, cache state, and power considerations, and it may well move the process to a different core than it used last time if that improves overall system balance.
What Changes With a CPUSet in Place
Once a container is pinned via a cpuset, the kernel scheduler’s list of eligible cores for that container’s processes shrinks down to only the specified subset. The scheduler can still move the process between the cores within that subset, but it can never place it on any core outside that set, no matter how idle that other core might be. This is the mechanism, enforced directly by the kernel, not by Docker itself at runtime — once the cpuset is configured, Docker’s job is done, and the kernel takes over enforcement for the life of the container.
sequenceDiagram
participant Sched as Kernel Scheduler
participant CS as cpuset cgroup
participant Proc as Container Process
Sched->>CS: Which cores is this process allowed to use?
CS-->>Sched: Only cores 0 and 1
Sched->>Proc: Schedule on core 0 or core 1 only
Note over Sched,Proc: Even if cores 2 and 3 sit completely idle, this process never runs there
Why This Improves Cache Locality
Modern CPUs have small, extremely fast memory caches built directly into each core. When a process keeps getting moved between cores, it repeatedly loses the “warm” data sitting in its previous core’s cache and has to reload that data into the new core’s cache — a real, measurable performance cost. A pinned process, by staying on the same core (or small set of cores) continuously, keeps its working data hot in that core’s cache far more consistently, which is the primary reason pinning can noticeably improve performance for latency-sensitive workloads.
4Data Flow and Lifecycle of a Pinned Container
Here’s the full sequence of what happens from container creation to teardown when CPU pinning is involved.
Container is created with a specified CPU set
The desired core range is provided as part of the container’s runtime configuration, before the container’s main process ever starts.
Docker creates the corresponding cpuset cgroup
The container runtime configures a kernel cgroup entry that records exactly which cores this container’s processes are permitted to use.
The container’s process is launched inside that cgroup
From the very first instruction it executes, the container’s main process is already subject to the core restriction — there’s no window where it runs unrestricted.
The kernel scheduler enforces the restriction continuously
For the entire runtime of the container, every scheduling decision respects the cpuset boundary automatically, with no further involvement from Docker itself.
Container stops, and the cgroup is torn down
When the container is removed, its cpuset cgroup is cleaned up, and the cores it had reserved become available again for other containers or processes to use.
5Advantages and Trade-offs
CPU pinning is a powerful tool, but it trades away flexibility for predictability — and that trade isn’t right for every workload.
Advantages
- Dramatically more predictable, consistent latency for time-sensitive workloads
- Better CPU cache locality, since the process stays on the same core rather than migrating
- Prevents “noisy neighbor” containers from stealing CPU time away from a critical workload’s dedicated cores
- Enables isolating specific cores entirely for one high-priority container, away from general system activity
- Essential for workloads that must meet strict, real-time performance guarantees
Disadvantages / Trade-offs
- Reduces overall system flexibility — pinned cores can sit idle even when the pinned container isn’t using them fully
- Can lead to poor overall CPU utilization if pinning decisions aren’t planned carefully across all containers on a host
- Adds operational complexity — pinning strategy must be actively managed as workloads and hardware change
- Misconfigured pinning (for example, overlapping cores between unrelated critical containers) can create contention instead of solving it
- Not portable across machines with different core counts or topologies without reconsidering the pinning strategy
6Security Implications
CPU pinning isn’t primarily a security feature, but it does intersect with security and reliability in a few important ways.
In multi-tenant environments, pinning can help ensure that one tenant’s runaway or malicious workload — even one deliberately trying to consume excessive CPU — is physically confined to a limited set of cores, protecting the CPU availability of critical containers running on other, separately pinned cores.
Because pinning places specific containers on specific, known physical cores, it can, in highly sensitive environments, be a consideration in defending against CPU cache-based side-channel attacks — where isolating security-critical workloads onto dedicated cores separate from untrusted workloads reduces certain classes of cross-container information leakage risk.
It’s worth being clear that pinning alone is not a complete isolation or security boundary — it should be combined with the rest of Docker’s standard isolation mechanisms (namespaces, cgroup memory limits, and so on) rather than relied upon in isolation.
7Pinned vs. Unpinned: A Direct Comparison
A side-by-side look at how pinned and unpinned containers behave under the same conditions.
| Aspect | Unpinned Container | Pinned Container |
|---|---|---|
| Core selection | Chosen freely by the kernel scheduler | Restricted to an explicitly configured set of cores |
| Cache locality | Variable — can degrade as the process migrates | Consistently strong, since the process stays on the same cores |
| Latency predictability | Can vary with overall system load | Highly predictable, largely independent of unrelated system activity |
| Overall host CPU utilization | Generally higher, since any idle core can be used | Can be lower if pinned cores sit idle when demand is low |
| Best suited for | General-purpose, bursty, non-latency-critical workloads | Real-time, latency-sensitive, or high-throughput dedicated workloads |
8Design Patterns and Anti-patterns
CPU pinning is easy to misuse if applied without a clear strategy — here’s what tends to work, and what tends to backfire.
Problem
Pinning every single container on a host to specific cores “for consistency,” including low-priority, bursty workloads that don’t need it.
Why It’s Harmful
This fragments the host’s CPU capacity into rigid silos, often leaving some cores idle while others are overloaded, hurting overall utilization without providing any real benefit to workloads that never needed strict pinning in the first place.
Correct Approach
Reserve pinning for the specific workloads that genuinely require predictable, low-latency CPU access, and leave general-purpose containers unpinned so the scheduler can balance them efficiently.
Problem
Pinning multiple unrelated, CPU-hungry containers to the exact same set of cores.
Why It’s Harmful
This recreates the exact contention problem pinning was meant to solve, except now it’s confined to a smaller set of cores, which can actually make contention worse than leaving the containers unpinned.
Correct Approach
Plan pinning assignments holistically across all containers on a host, ensuring that containers sharing a core set genuinely complement each other’s usage patterns rather than compete for the same cycles.
Problem
A latency-sensitive service, such as a real-time data processing or trading system, needs consistent, predictable response times regardless of what else is running on the host.
Why It Works
Pinning that service to a small, dedicated set of cores — ideally isolated from general system activity — removes scheduler-induced jitter and cache-migration overhead as sources of latency variance.
Correct Approach
Reserve specific cores exclusively for the latency-critical container, and keep all other, less sensitive workloads pinned elsewhere or left unpinned entirely.
9Monitoring, Metrics, and Best Practices
Because the benefits of pinning are only real if it’s configured correctly, ongoing observation is essential.
Per-core utilization
Tracking utilization on each individual core reveals whether pinned cores are being used effectively or sitting needlessly idle.
Context switch rate
A lower context switch rate on pinned cores compared to unpinned ones is a good signal that pinning is delivering its intended cache-locality benefit.
Tail latency (p99 / p999)
For latency-sensitive pinned workloads, tracking tail latency percentiles — not just averages — is the most direct way to confirm pinning is actually improving predictability.
Host-wide CPU balance
Comparing overall utilization across pinned and unpinned regions of the host helps catch cases where pinning has fragmented capacity inefficiently.
Setting a pinning strategy once and never revisiting it is a frequent oversight — as workloads change, new containers are added, or hardware is upgraded, a pinning layout that made sense originally can quietly become a source of contention or wasted capacity.
10Real-World and Industry Examples
CPU pinning shows up wherever consistent, low-latency performance is non-negotiable.
High-Frequency Trading and Financial Systems
Systems where microseconds of latency variance have real financial consequences routinely pin critical containers to dedicated, isolated cores to eliminate scheduler-induced jitter as a source of unpredictability.
Telecommunications and Network Function Virtualization
Software that handles real-time packet processing for telecom infrastructure commonly relies on CPU pinning to guarantee the consistent throughput and low latency that networking hardware traditionally provided.
High-Performance Computing and Scientific Workloads
Compute-intensive scientific simulations pin worker processes to specific cores, often combined with NUMA node binding, to maximize cache efficiency and memory access speed across long-running, resource-intensive jobs.
11Frequently Asked Questions
No. CPU pinning controls which specific cores a container is allowed to run on, while CPU shares and quotas control how much total CPU time it’s entitled to. The two mechanisms work independently and can be combined.
No. It helps predictable, latency-sensitive, or cache-intensive workloads, but for general-purpose or bursty workloads it can actually reduce overall efficiency by preventing the scheduler from balancing load across all available cores.
Docker uses the cpuset subsystem of Linux control groups (cgroups), which lets the kernel restrict a group of processes to a specific set of CPU cores and, optionally, specific memory nodes.
Yes, technically, but doing so recreates contention between those two containers on the shared cores, which usually defeats the purpose of pinning unless it’s an intentional, carefully planned trade-off.
Its benefits shrink significantly on machines with very few cores, since there’s little room to dedicate cores exclusively to one workload without starving everything else. Pinning delivers the most value on machines with many available cores.
It provides some resource-based isolation benefits and can be one factor in mitigating certain side-channel risks, but it is not a substitute for Docker’s core isolation mechanisms like namespaces and should be combined with them, not relied on alone.
12Summary and Key Takeaways
CPU pinning and cpusets give you a direct lever over one of the things Docker normally hides from you entirely: exactly which physical cores your containers run on. For most workloads, leaving that decision to the kernel scheduler is the right call — it’s efficient, flexible, and requires zero extra thought. But for workloads where predictable, low-latency performance matters more than raw flexibility, pinning transforms a container from a guest that shares whatever core happens to be free into a tenant with its own permanently reserved space on the machine, free from the cache-thrashing and scheduling jitter that comes with constant core migration.
Key Takeaways
- Pinning restricts, it doesn’t allocate time — cpusets control which cores a container may use, separately from how much CPU time it’s entitled to.
- Built on cpuset cgroups — Docker implements pinning using the same Linux kernel cgroup mechanism it already relies on for other resource controls.
- Improves cache locality — keeping a process on the same core avoids the performance cost of repeatedly reloading data into a new core’s cache.
- Enforced entirely by the kernel — once configured, the kernel scheduler enforces the restriction automatically for the life of the container.
- Trades flexibility for predictability — pinned cores can sit idle even under load elsewhere, so over-pinning hurts overall utilization.
- Best for latency-critical, dedicated workloads — real-time, financial, telecom, and high-performance computing workloads benefit most.
- Requires ongoing management — pinning layouts should be revisited as workloads, container counts, and hardware evolve.