hwloc-ls

View documentation for the original command

$ tldr lstopo-no-graphics

hwloc-ls [options] [location]

-b, --no-colors
    Disable color output.

-c <types>, --only <types>
    Restrict to object types (e.g. PU,Core,L2Cache).

-d <depth>, --depth <depth>
    Limit display to given logical depth.

--if <regex>
    Show I/O only through matching PCI links.

-i <file>, --input <file>
    Load topology from XML file instead of system.

--location
    Restrict to specified location (os/osdev,pci,...).

--of <format>
    txt (default), csv, json, xml output format.

-p, --physical
    Use physical indexes instead of logical.

-s
    Show cpusets only, no object names.

--skip <regex>
    Skip objects matching regular expression.

-v, --verbose
    Increase verbosity level.

-V, --version
    Report hwloc version.

--whole-io
    Force I/O device discovery.

--whole-system
    Detect entire system, bypass restrictions.

hwloc-ls is a utility from the Hardware Locality (hwloc) project that prints a hierarchical view of the system's processing, memory, and I/O topology in a compact tree format using ASCII art. It reveals the structure of processors (PUs, cores, packages), caches (L1/L2/L3), NUMA nodes, and optionally I/O devices like GPUs and NICs.

This tool helps HPC developers, system admins, and performance engineers visualize binding opportunities for MPI/OpenMP tasks, NUMA-aware memory placement, and hardware affinities to maximize application performance. Output is color-coded by default (green for cores, blue for caches, etc.) for quick parsing.

hwloc-ls can load topologies from XML files, restrict to depths/types/locations, and export to structured formats like JSON/XML/CSV for automation. It honors current process affinity and supports whole-system discovery with elevated privileges, ignoring local restrictions.

Ideal for quick topology checks without graphical tools like lstopo, it provides essential insights into multi-socket, multi-core, heterogeneous systems.

Root privileges often needed for full topology (--whole-system). Colors require ANSI terminal support. I/O discovery may fail without kernel support.

Machine, NUMANode, Package, L3Cache, Core, PU, OSDev, PCI.

hwloc-ls --whole-system for full view.
hwloc-ls -d 4 limit depth.
hwloc-ls --of json for parsing.

Introduced in hwloc 1.11 (2013) as lightweight alternative to lstopo. Enhanced in hwloc 2.x with JSON/CSV output, better regex filtering, and I/O support.

lstopo(1), hwloc-info(1), hwloc-bind(1), lscpu(1), lspci(8)