HWLOC-GATHER-TOPOLOGY(1)

💅 HWLOC-GATHER-TOPOLOGY(1) 💅

ok so like, this page lives in the hwloc manual, and it's genuinely one of the most useful little tools ever — it's hwloc-gather-topology, and it's basically a screenshot button for your machine's whole soul. ✨

---

🌸 NAME 🌸

hwloc-gather-topology — saves all the relevant Linux and x86 topology files, plus the lstopo textual and XML outputs, so you can vibe with them later (possibly offline, bestie 💖).

---

🦋 SYNOPSIS 🦋

hwloc-gather-topology [options] <path>

---

✨ OPTIONS ✨

• --io — also gathers I/O related files. heads up though: the gathering may be much slower, and the archive it makes may be much bigger. it's giving "worth it but be patient" 🫶
• --dmi — also gathers DMI/SMBIOS related files. this one requires root access, and the dmi-sysfs kernel module should be loaded. no cap, it's a whole thing.
• --dt — also gathers Device-Tree CPU files. these files aren't needed for hwloc itself, but they may be used for debugging what Linux exposes in /sys. lowkey just for the nerds (affectionate) 🧚
• --no-cpuid — do not gather the x86 CPUID dump using hwloc-gather-cpuid.
• --keep — keep the temporary copy of the dumped files instead of destroying it. hoarder mode: activated 💅
• --version — report version and exit. short and iconic.
• -h, --help — display the help message and exit. we love a self-aware king 👑

---

💜 DESCRIPTION 💜

okay so here's the tea: hwloc-gather-topology saves all the relevant topology files into an archive (<path>.tar.bz2), the lstopo output (<path>.output), and the lstopo XML (<path>.xml). for example, it stores the /proc/cpuinfo file and the entire /sys/devices/system/node/ directory tree. like, the whole tree. 🌳

these files can be used later to explore the machine topology offline — main character energy for real. once the tarball has been extracted, it may for instance be given to some hwloc command-line utilities through their --input option. it is also possible to override the default topology that the hwloc library will read by setting the extracted path in the HWLOC_FSROOT environment variable. 🔥

the archive and the lstopo textual and XML outputs may also be submitted to hwloc developers to debug issues remotely. remote debugging slay 💖

hwloc-gather-topology is a Linux specific tool — it is not installed on other operating systems. sorry to the BSD girlies 😭

NOTE: hwloc-gather-topology gathers many hardware details about the platform. the outputs and tarball should not be posted on public lists or websites unless it is clear that they contain no sensitive information. fr fr, do a vibe check before you post 🚨

NOTE: the gathering may take several minutes, especially on large nodes. grab a snack, bestie. 🍓

NOTE: it is highly recommended that you read the hwloc(7) overview page before reading this man page. homework first, then chaos 📚

---

🌈 EXAMPLES 🌈

to store topology information to be used later (possibly on a different host) please run:

$ hwloc-gather-topology /tmp/myhost

it will store all relevant topology files in the /tmp/myhost.tar.bz2 archive, the lstopo output in the /tmp/myhost.output file, and the lstopo XML in the /tmp/myhost.xml file. these files can be transferred on another host for later/offline analysis and/or as the input to various hwloc utilities. it's literally packing a little suitcase for your topology 🧳

to use these data with hwloc utilities you should unpack myhost.tar.bz2 archive first:

$ tar jxvf /tmp/myhost.tar.bz2

a new directory named myhost now contains all topology files. then you ask various hwloc utilities to use this topology instead of the one of the real machine by passing --input myhost. to display the topology just run:

$ lstopo --input ./myhost

it is not necessary that the topology is extracted in the current directory — absolute or relative paths are also supported:

$ lstopo --input /path/to/remote/host/extracted/topology/

unpacking is actually only required for the hwloc C API. if the archivemount tool is available, command-line tools such as lstopo may actually read directly from the tarball. note however that this mode may be slow for large tarballs. we love a shortcut with a caveat 🎀

$ lstopo --input /tmp/myhost.tar.bz2

to see how hwloc would distribute 8 parallel jobs on the original host:

$ hwloc-distrib --input myhost --single 8

to get the corresponding physical indexes in the previous command:

$ hwloc-calc --input myhost --po --li -I pu $(hwloc-distrib --input
myhost --single 8)

any program may actually override the default topology with a given archived one even if it does not have a --input option. the HWLOC_FSROOT environment variable should be used to do so:

$ HWLOC_FSROOT=myhost hwloc-calc --po --li -I pu $(hwloc-distrib
--single 8)

all these commands will produce the same output as if executed directly on the host on which the topology information was originally gathered by the hwloc-gather-topology script. it's giving time travel, honestly ⭐

---

🎀 RETURN VALUE 🎀

upon successful execution, hwloc-gather-topology will exit with the code 0. we love a clean zero ✨

hwloc-gather-topology will return nonzero exit status if any kind of error occurs, such as (but not limited to) failure to create the archive or output files. if you see that, something's off and we're sad about it 😭

---

👑 SEE ALSO 👑

hwloc(7), lstopo(1), hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-distrib(1)

---

and that's the whole page, bestie 🫶 this is version 2.15.0, dated Sep 23, 2026 — go gather some topology, you absolute icon 💜🦋