HWLOC-PS(1)

💅 HWLOC-PS(1) — the hwloc manual, bestie edition ✨

okay so you found the page for hwloc-ps, part of the hwloc manual set — congrats, you're about to know exactly which processes are pinned to what. let's go 🎀

---

🌸 NAME 🌸

hwloc-ps — lists all the currently-running processes or threads that are bound, iykyk. that's literally the whole job 💖

---

⭐ SYNOPSIS ⭐

hwloc-ps [options]

---

🦋 OPTIONS 🦋

• -a — show everything, even the processes that aren't bound to any particular part of the machine. no filter, no gatekeeping 👑
• --pid <pid> — only show the process with PID <pid>, even if it's not bound to anything specific. just that one. main character only 💅
• --children-of-pid <pid> — show the process with PID <pid> and its whole hierarchy of children, even if they're not bound to any specific part of the machine. family tree slay 🌈
• --name <name> — only show processes whose name contains <name>, even if they're not bound to any specific part of the machine. ⚠️ heads up: this is not supported on all operating systems, so vibe-check your OS first.
• --uid <uid> — only show processes belonging to the user whose UID is <uid>, or processes of all users if all is given. by default only the current user's processes are displayed. 🐧 this is currently only supported on Linux.
• -p, --physical — report OS/physical indexes instead of logical indexes.
• -l, --logical — report logical indexes instead of physical/OS indexes. this is the default, so if you do nothing you're already here 🫶
• -c, --cpuset — show process bindings as cpusets instead of objects.
• -t, --threads — show threads inside processes. if -a is also given, list all threads within each process. otherwise, show all threads inside each process where at least one thread is bound. 🐧 this is currently only supported on Linux.
• --single-ancestor — when the object is bound to different objects, report their common ancestor instead (even if that ancestor may be larger than the actual binding). lowkey a glow-up for readability ✨
• -e, --get-last-cpu-location — report the last processors where the process/thread ran. 😭 big caveat: the result may already be outdated by the time you see it, because the operating system can move tasks to other processors at any time according to the binding. it's giving racing conditions.
• --disallowed — include objects disallowed by administrative limitations.
• --pid-cmd <cmd> — append the output of the given command to each PID line. for each displayed process ID, it executes <cmd> <pid> and appends the first line of its output to the regular hwloc-ps line. 🫶
• --pid-cmd env=<name> — on Linux, try to read the value of the environment variable name in each process and display it at the end of the line. 🐧
• --pid-cmd mpirank — on Linux, try to find the process's MPI rank (by querying some widespread environment variables) and display it at the end of the line. 🐧
• --lstopo-misc <file> — output a file that may be given to lstopo --misc-from for displaying processes/threads as Misc objects. peep the EXAMPLES below 👀
• --json-server — run the tool as a JSON server that waits for other processes' requests on a port and sends back binding information. see contrib/hwloc-ps.www/ for the deets 📂
• --json-port <port> — use the given port number instead of the default 8888. 🔌
• -v, --verbose — increase verbosity of the JSON server. chatty queen 💬
• --short-name — show only the process short name instead of the path. concise icon 🎀
• --version — report version and exit.
• -h, --help — display help message and exit.

---

💜 DESCRIPTION 💜

by default, hwloc-ps lists only those currently-running processes that are bound. if -t is given, processes that aren't bound but contain at least one bound thread are also displayed — plus all their threads. no cap, that's the whole filter logic 🧚

hwloc-ps displays the process identifier, the command-line, and the binding. the binding may be reported as objects or as cpusets.

by default, process bindings are restricted to the currently available topology. so if some processes are bound to processors that are not available to the current process, they get ignored — unless you pass --disallowed. 🙈

the output is a plain list. if you actually want to annotate the hierarchical topology with processes so you can see how they're really distributed on the machine, you might wanna use lstopo --ps instead (which also only shows processes that are bound). different tool, different vibe 🦋

and the -a switch can be used to show all processes, if that's what you're into. go off 💅

---

🔥 EXAMPLES 🔥

if a process is bound, it shows up in the default output:

$ hwloc-ps
4759 Core:0         myprogram

if a process is bound on two cores of a larger package, the output shows those cores. but --single-ancestor will instead return the package — even if it's actually larger than the binding here (the process is not bound to Core:0 of Package:0):

$ hwloc-ps
4863        Core:1 Core:2   myprogram
$ hwloc-ps --single-ancestor
4863        Package:0       myprogram

if a process is not bound but 3 of its 4 threads are bound, it only appears in the thread-aware output (or if it's explicitly selected):

$ hwloc-ps

$ hwloc-ps -t
4759 Machine:0      myprogram
 4759 Machine:0
 4761 PU:0
 4762 PU:2
 4765 PU:1

$ hwloc-ps --pid 4759
4759 Machine:0      myprogram

🎀 Example with lstopo integration

the output may be a file that lstopo uses for adding Misc objects (a more flexible version of lstopo --top):

$ hwloc-ps --misc-from foo
$ cat foo
name=12444 myprogram
cpuset=0x000000f0
subtype=Process

name=12444 mythread1
cpuset=0x00000050
subtype=Thread

name=12444 mythread2
cpuset=0x000000a0
subtype=Thread

and this may be directly given to lstopo:

$ hwloc-ps --misc-from - | lstopo --misc-from -

🌈 Examples with MPI processes

on Linux, hwloc-ps may also display some process-specific environment variable at the end of the line. this is, for instance, useful for identifying MPI ranks among processes:

$ hwloc-ps --pid-cmd env=OMPI_COMM_WORLD_RANK
29093     PU:0 myprogram OMPI_COMM_WORLD_RANK=0
29094     PU:2 myprogram OMPI_COMM_WORLD_RANK=1
29095     PU:1 myprogram OMPI_COMM_WORLD_RANK=2
29096     PU:3 myprogram OMPI_COMM_WORLD_RANK=3

some widespread MPI-specific environment variables (OMPI_COMM_WORLD_RANK, PMIX_RANK, PMI_RANK and SLURM_PROCID) are actually directly recognized by hwloc-ps when you request the mpirank command:

$ hwloc-ps --pid-cmd mpirank
29093     PU:0 myprogram PMIX_RANK=0
29094     PU:2 myprogram PMIX_RANK=1
29095     PU:1 myprogram PMIX_RANK=2
29096     PU:3 myprogram PMIX_RANK=3

besides reading environment variables, hwloc-ps may also append the output of a custom program. again, for reading the Open MPI process rank:

$ hwloc-ps --pid-cmd myscript
29093     PU:0 myprogram OMPI_COMM_WORLD_RANK=0
29094     PU:2 myprogram OMPI_COMM_WORLD_RANK=1
29095     PU:1 myprogram OMPI_COMM_WORLD_RANK=2
29096     PU:3 myprogram OMPI_COMM_WORLD_RANK=3

where myscript is a shell script doing:

#!/bin/sh
cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo |
grep OMPI_COMM_WORLD_RANK

---

👑 SEE ALSO 👑

hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1), and hwloc-ps.www/README — go read them, they're iconic too 💖

---

anyway that's the whole page, bestie. this edition was brought to you by 2.15.0, dated Sep 23, 2026 — mwah, go pin some processes 💅✨🎀