---
name: "hwloc-gather-topology"
section: "1"
platform: "linux"
package: "hwloc"
version: "2.15.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hwloc-gather-topology"
---

# hwloc-gather-topology(1)

Saves the relevant Linux and x86 topology files and the lstopo textual and XML outputs for later (possibly offline) usage

## NAME

hwloc-gather-topology - Saves the relevant Linux and x86 topology files and the lstopo textual and XML outputs for later (possibly offline) usage

## SYNOPSIS

**hwloc-gather-topology \[*options*\] *\<path\>***

## OPTIONS

- **--io**

  Also gather I/O related files. The gathering may be much slower, and the generated archive may be much bigger.

- **--dmi**

  Also gather DMI/SMBIOS related files. The gathering requires root access, and the dmi-sysfs kernel module should be loaded.

- **--dt**

  Also gather Device-Tree CPU files. These files aren't needed for hwloc, but they may be used for debugging what Linux exposes in /sys.

- **--no-cpuid**

  Do not gather x86 CPUID dump using *hwloc-gather-cpuid*.

- **--keep**

  Keep the temporary copy of dumped files instead of destroying it.

- **--version**

  Report version and exit.

- **-h** **--help**

  Display help message and exit.

## DESCRIPTION

**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**). The utility for example stores the **/proc/cpuinfo** file and the entire **/sys/devices/system/node/** directory tree.

These files can be used later to explore the machine topology offline. 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.

**hwloc-gather-topology** is a Linux specific tool, it is not installed on other operating systems.

**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.

**NOTE:** The gathering may take several minutes, especially on large nodes.

**NOTE:** It is highly recommended that you read the [hwloc(7)](/hwloc/7.md) overview page before reading this man page.

## 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.

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.

    $ 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.

## RETURN VALUE

Upon successful execution, **hwloc-gather-topology** will exit with the code 0.

**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.

## SEE ALSO

[hwloc(7)](/hwloc/7.md), [lstopo(1)](/lstopo/1.md), [hwloc-gather-cpuid(1)](/hwloc-gather-cpuid/1.md), [hwloc-calc(1)](/hwloc-calc/1.md), [hwloc-distrib(1)](/hwloc-distrib/1.md)