HWLOC-BIND(1)

hwloc-bind(1) — the hwloc manual page, but make it make sense 💅

💖 NAME 💖

hwloc-bind — launch a command that is bound to specific processors and/or memory, or consult the binding of an existing program. Basically: you tell it where your process is allowed to run, and it handles the launch or the vibe check 🫶

✨ SYNOPSIS ✨

hwloc-bind [topology options] [options] <location1> [<location2> [...] ]
[--] <command> ...

Also, bestie: hwloc(7) is the detailed lore drop on the whole hwloc system and every valid <location> format — read that before this page, fr fr 💖

🧚 TOPOLOGY OPTIONS 🧚

🚨 all topology options must be given before all other options — no sneaking them in later, okay? 💅

• --no-smt, --no-smt=<N> — only keep the first PU per core before binding. If <N> is specified, keep the <N>-th instead, if any. PUs are ordered by physical index during this filtering ✨

Note that this option is applied after searching locations. So --no-smt pu:2-5 will first select the PUs #2 to #5 in the machine before binding on one of them per core. To rather bind on PUs #2 to #5 after filtering one per core, you should combine with hwloc-calc:

hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --no-smt all) pu:2-5) -- echo hello

• --restrict <cpuset> — restrict the topology to the given cpuset. This removes some PUs and their now-child-less parents. Beware: restricting the PUs in a topology may change the logical indexes of many objects, including NUMA nodes 😭
• --restrict nodeset=<nodeset> — restrict the topology to the given nodeset (unless --restrict-flags specifies something different). This removes some NUMA nodes and their now-child-less parents. Beware: restricting the NUMA nodes in a topology may change the logical indexes of many objects, including PUs 💀
• --restrict-flags <flags> — enforce flags when restricting the topology. Flags may be given as numeric values or as a comma-separated list of flag names that are passed to hwloc_topology_restrict(). Those names may be substrings of actual flag names as long as a single one matches, for instance bynodeset,memless. The default is 0 (or none) 🎀
• --disallowed — include objects disallowed by administrative limitations 👑
• --best-memattr <name> — select the best NUMA node(s) among the given memory binding set by looking at the memory attribute given by <name> (or as an index). If the memory attribute values depend on the initiator, the CPU binding set is used as the initiator 🧚

Standard attribute names are Capacity, Locality, Bandwidth, and Latency. All existing attributes in the current topology may be listed with:

$ lstopo --memattrs

<name> may be suffixed with flags to tune the selection of best nodes, for instance as bandwidth,strict,default 🔥

default means that default nodes are reported if no best could be found (see --default-nodes). If neither best nor default nodes could be found, all local nodes are reported 🌸

strict means that nodes are selected only if their performance is the best for all the input CPUs. On a dual-socket machine with HBM in each socket, both HBMs are the best for their local socket, but not for the remote socket. Hence both HBM are also considered best for the entire machine by default, but none if strict 😭

• --default-nodes — only keep default NUMA nodes. This usually includes DRAM memory nodes (or nodes of the same memory tier) rather than nodes with specific characteristics (HBM, NVM, CXL, etc). See hwloc_topology_get_default_nodeset() for details 🫶
• --hbm — only take high bandwidth memory nodes (marked with "HBM" subtype, or "MCDRAM" on Intel Xeon Phi) in account when looking for NUMA nodes in the input locations. This option must be combined with NUMA node locations, such as --hbm numa:1 for binding on the second HBM node. It may also be written as numa[hbm]:1 or numa[mcdram]:1 ⭐
• --no-hbm — ignore high bandwidth memory nodes (marked with "HBM" subtype, or "MCDRAM" on Intel Xeon Phi MCDRAM) when looking for NUMA nodes in the input locations 🙈

🌈 OPTIONS 🌈

💅 all of these options must be given after all topology options above.

• --cpubind — use following arguments for CPU binding (default) 🎀
• --membind — use following arguments for memory binding. If --mempolicy is not also given, the default policy is bind 💖
• --mempolicy <policy> — change the memory binding policy.

This option is only meaningful when an actual binding is also given with --membind. If --membind is given without --mempolicy, the default policy is bind ✨

The available policies are default, firsttouch, bind, interleave, weighted (interleave) and nexttouch. See hwloc.h for details about these policies 🔥

Note that hwloc's memory binding policies may be slightly different from operating system policies. For instance, the hwloc bind policy uses Linux MPOL_PREFERRED_MANY (or MPOL_PREFERRED) by default, but it switches to Linux MPOL_BIND if the hwloc strict option or flag is also given 💅

• --get — report the current bindings. The output is an opaque bitmask that may be translated into objects with hwloc-calc (see EXAMPLES below) 👑

When a command is given, the binding is displayed before executing the command. When no command is given, the program exits after displaying the current binding 🌸

When combined with --membind, report the memory binding instead of CPU binding 🫶

No location may be given since no binding is performed 🚨

• --nodeset — report binding as a NUMA memory node set instead of a CPU set if --get was given. This is useful for manipulating CPU-less NUMA nodes since their cpuset is empty while their nodeset is correct 🧚

Also parse input bitmasks as nodesets instead of cpusets ✨

When this option is not passed, individual input bitmasks may still be parsed as nodesets if they are prefixed with nodeset= 🎀

• -e, --get-last-cpu-location — report the last processors where the process ran. The output is an opaque bitmask that may be translated into objects with hwloc-calc (see EXAMPLES below) 😭

Note that the result may already be outdated when reported since the operating system may move the process to other processors at any time according to the binding 💀

When a command is given, the last processors is displayed before executing the command. When no command is given, the program exits after displaying the last processors 🦋

This option cannot be combined with --membind 🚨

No location may be given since no binding is performed 🙈

• --single — bind on a single CPU to prevent migration 🎯
• --strict — require strict binding 🔒
• --pid <pid> — operate on pid <pid> 👑
• --tid <tid> — operate on thread <tid> instead of on an entire process. The feature is only supported on Linux for thread CPU binding, or for reporting the last processor where the thread ran if -e was also passed 🌈
• -p, --physical — interpret input locations with OS/physical indexes instead of logical indexes. This option does not apply to the output, see --get above 💅
• -l, --logical — interpret input locations with logical indexes instead of physical/OS indexes (default). This option does not apply to the output, see --get above ✨
• --cpuset-output-format <hwloc|list|taskset>, --cof <hwloc|list|taskset> — change the format of CPUset or nodeset strings displayed by --get, -e, etc. By default, the hwloc-specific format is used. If list is given, the output is a comma-separated of numbers or ranges, e.g. 2,4-5,8 . If taskset is given, the output is compatible with the taskset program (replaces the former --taskset option) 🎀

This option has no impact on the format of input CPU set strings, hwloc, list and taskset formats are always accepted. In case of ambiguity, use hwloc-calc --cpuset-input-format 🫶

• -f, --force — launch the executable even if binding failed 💥
• -q, --quiet — hide non-fatal error messages. It includes locations pointing to non-existing objects, as well as failure to bind. This is usually useful in addition to --force 🤫
• -v, --verbose — verbose output 🗣️
• --version — report version and exit 📦
• -h, --help — display help message and exit 🆘

🦋 DESCRIPTION 🦋

hwloc-bind execs an executable (with optional command line arguments) that is bound to the specified location (or list of locations). Location specification is described in hwloc(7). Upon successful execution, hwloc-bind simply sets bindings and then execs the executable over itself ✨

If a bitmask location is given with prefix nodeset=, then it is considered a nodeset instead of a CPU set. See also --nodeset 🎀

If multiple locations are given, they are combined in the sense that the binding will be wider. The process will be allowed to run on every location inside the combination 🌈

The list of input locations may be explicitly ended with -- 💅

If binding fails, or if the binding set is empty, and --force was not given, hwloc-bind returns with an error instead of launching the executable 🚨

🌟 NOTE: It is highly recommended that you read the hwloc(7) overview page before reading this man page. Most of the concepts described in hwloc(7) directly apply to the hwloc-bind utility 💖

✨ EXAMPLES ✨

okay bestie, the vibe of hwloc-bind is honestly best explained by just... showing you stuff 🫶. and if you want the full tea on how locations get written on the command line, that's all in hwloc(7).

---

🌸 Examples with plain old CPU binding

So you wanna run echo on the first logical processor of the second package? iconic, do that:

$ hwloc-bind package:1.pu:0 -- echo hello

and like, that's literally the exact same thing as this next line, as long as there's no ambiguity between hwloc-bind option names and the name of the command you're running:

$ hwloc-bind package:1.pu:0 echo hello

Now say you want echo on the first core of the second package and the second core of the first package — multitasking queen 💅:

$ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello

Wanna hit the first PU of all the cores of the first package? two ways, same energy:

$ hwloc-bind package:0.core:all.pu:0 -- echo hello
$ hwloc-bind --no-smt package:0 -- echo hello

And the --get option? that's your little reporter ✨ it tells you the bindings you currently have. this example nests hwloc-bind calls — one to set the binding, one to report it:

$ hwloc-bind node:1.package:2 -- hwloc-bind --get
0x00004444,0x44000000

---

🧚 Examples with memory binding

To bind on a specific node and just let the OS place the execution however it wants:

$ hwloc-bind --membind node:2 -- echo hello

To bind memory on the second memory node and run on the first node (only when the OS supports it, no cap):

$ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello

To bind on the memory node(s) local to the PU with the largest capacity:

$ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind pu:23 -- echo hello

To bind on the default memory node near a package:

$ hwloc-bind --default-nodeset --membind package:1 -- echo hello

To bind memory on the first NUMA node tagged with the "HBM" subtype:

$ hwloc-bind --membind numa[hbm]:0 -- echo hello
$ hwloc-bind --hbm --membind numa:0 -- echo hello

And to bind memory on the first high-bandwidth memory node (MCDRAM) on Intel Xeon Phi:

$ hwloc-bind --membind numa[mcdram]:0 -- echo hello
$ hwloc-bind --hbm --membind numa:0 -- echo hello

real talk though 🙈 — binding the echo command to multiple processors is probably meaningless (because echo is likely implemented as a single-threaded application). these examples are just here to show off what hwloc-bind can do, periodt.

Your current memory binding can be reported too, bestie:

$ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind --get --membind
0x000000f0 (interleave)

---

🦋 Examples with advanced resource specification

To run on the first three packages on the second and third nodes:

$ hwloc-bind node:1-2.package:0:3 -- echo hello

which is also equivalent to:

$ hwloc-bind node:1-2.package:0-2 -- echo hello

⚠️ heads up: if you try to bind to objects that don't exist, hwloc-bind will not warn you unless -v was specified. so like, don't come for her when she's silent, she told you.

To run on the core with physical index 2 in the package with physical index 1:

$ hwloc-bind --physical package:1.core:2 -- echo hello

To run on odd cores within even packages (chaotic, love that for you):

$ hwloc-bind package:even.core:odd -- echo hello

To run on the first package except on its second and fifth cores:

$ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo hello

To run literally anywhere except on the first package:

$ hwloc-bind all ~package:0 -- echo hello

---

🎀 Examples with I/O devices

To run on a core near the network interface named eth0:

$ hwloc-bind os=eth0 -- echo hello

To run on a core near the PCI device whose bus ID is 0000:01:02.0:

$ hwloc-bind pci=0000:01:02.0 -- echo hello

---

💜 Examples with hwloc-calc help

ngl, hwloc-bind does not have an option to select a kind of CPU core — but bestie, you can just combine it with hwloc-calc and slay anyway 💅. for instance, to bind on the first two cores whose kind matches CoreType=IntelAtom:

$ hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --cpukind CoreType=IntelAtom all) core:0-1) -- echo hello

hwloc-calc can also convert cpu mask strings into human-readable package/core/PU strings — peep the description of -H in hwloc-calc(1) for the full story. this next example binds to all the PUs in a specific core, uses the --get option to grab where the process actually got bound, then hands it to hwloc-calc to display that cpu mask as a space-delimited list of human-readable locations:

$ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -q -H package.core.pu
Package:1.Core:2.PU:0 Package:1.Core:2.PU:1

And hwloc-calc can turn that output into actual objects, either with logical or physical indexes:

$ hwloc-calc --physical -I pu `hwloc-bind --get`
26,30,34,38,42,46
$ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
24 25 26 27 28 29

Locations can also be given as a hex bit mask (typically generated by hwloc-calc). like so:

$ hwloc-bind 0x00004444,0x44000000 -- echo hello
$ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello

---

⭐ HINT ⭐

If the graphics-enabled lstopo is available, use for instance:

$ hwloc-bind core:2 -- lstopo --pid 0

to check what the result of your binding command actually is — lstopo will graphically show you where hwloc-bind bound it. visual confirmation, we love to see it 👑

---

🔥 RETURN VALUE 🔥

Upon successful execution, hwloc-bind execs the command over itself. so the return value is therefore whatever the return value of the command is. simple as that ✨

hwloc-bind will return nonzero if any kind of error occurs, such as (but not limited to): failure to parse the command line, failure to retrieve process bindings, or lack of a command to execute. so yeah, nonzero = something went sideways 😭

---

🌈 SEE ALSO 🌈

• hwloc(7)
• lstopo(1)
• hwloc-calc(1)
• hwloc-distrib(1)

---

and that's the whole page bestie!! 💖✨🎀🦋🌸💅🫶 this lil masterpiece is from 2.15.0, dated Sep 23, 2026 — go forth and bind responsibly, iykyk 😌👑