How to Visualise CPU Architecture, NUMA Nodes, and Cache Topology in Linux Using lstopo

Modern microprocessors integrate complex internal topologies, pairing performance and efficiency cores with multi-tiered cache hierarchies and Non-Uniform Memory Access (NUMA) domains. For system administrators, database architects, and software developers compiling parallel workloads, understanding the physical arrangement of hardware threads, shared L3 caches, and memory controllers is vital for thread affinity pinning and execution optimisation. The Portable Hardware Locality (hwloc) suite provides lstopo, a powerful utility that visualises Linux processor architectures and cache hierarchies in both graphical and command-line formats.

Why Hardware Topology Inspection Matters in Linux

While generic tools like lscpu and cat /proc/cpuinfo output raw text tables detailing core counts and clock frequencies, they fail to communicate spatial relationships between CPU execution units and system memory buses. In multi-socket servers and hybrid consumer processors (such as Intel Alder Lake/Raptor Lake architectures), assigning memory-intensive threads to cores that do not share a local L3 cache or direct NUMA memory channel introduces substantial latency penalties. The lstopo command renders an intuitive spatial map that clarifies precisely which logical processor IDs share execution caches, PCIe root complexes, and RAM banks.

Installing hwloc and lstopo Across Linux Distributions

The lstopo binary resides within the hwloc package. Install it using your distribution’s native package manager:

• Ubuntu, Debian, and Linux Mint:
  sudo apt update && sudo apt install hwloc
• Fedora, RHEL, and CentOS Stream:
  sudo dnf install hwloc
• Arch Linux and Manjaro:
  sudo pacman -S hwloc
• openSUSE:
  sudo zypper install hwloc

Rendering an ASCII Topology Tree Directly in the Terminal

On remote headless servers or minimal shell sessions lacking an X11 or Wayland display server, execute lstopo-no-graphics or pipe text output directly into your terminal:

lstopo --of console

The utility renders an ASCII tree mapping each hardware component from the machine level down to individual processing units (PU):

Machine (31GB total)
  Package L#0
    NUMANode L#0 (P#0 31GB)
    L3 L#0 (32MB)
      L2 L#0 (512KB) + L1d L#0 (32KB) + L1i L#0 (32KB) + Core L#0
        PU L#0 (P#0)
        PU L#1 (P#1)
      L2 L#1 (512KB) + L1d L#1 (32KB) + L1i L#1 (32KB) + Core L#1
        PU L#2 (P#2)
        PU L#3 (P#3)
  HostBridge
    PCIBridge
      PCI 01:00.0 (VGA compatible controller)

In this hierarchy, L# denotes the logical index used internally by hwloc, while P# indicates the physical OS processor ID assigned by the Linux kernel. This distinction ensures accurate CPU affinity binding with commands like taskset.

Exporting Graphical Topology Diagrams (PNG, PDF, and SVG)

For presentations, architecture documentation, or deep technical auditing, lstopo can render crisp, colour-coded vector or raster diagrams without requiring an interactive window. Supply an output filename with your desired file extension:

• Exporting to PNG:
  lstopo topology.png
• Exporting to SVG Vector Format:
  lstopo topology.svg
• Exporting to Portable Document Format (PDF):
  lstopo topology.pdf

The resulting graphic employs distinct colours for NUMA memory banks (green), shared L3 caches (cyan), individual L2/L1 cache blocks (yellow/white), and processing cores, providing a publication-ready visual overview of your system architecture.

Filtering for Physical Processor IDs and Hardware Bindings

When scripting thread affinity policies for hyperthreaded systems, it is essential to target physical core indices rather than abstract logical counters. Run lstopo with physical indexing enabled:

lstopo -p --of console

This flag switches all reported socket, core, and PU labels to physical OS numbers, ensuring complete parity with /sys/devices/system/cpu/ entries.

Inspecting PCIe Devices and Memory Node Distances

Beyond CPU units, lstopo detects connected peripheral buses, including NVMe storage controllers, high-speed network interfaces, and GPUs. To inspect input/output device linkages relative to local NUMA nodes, execute:

lstopo --no-caches --of console

Hiding cache blocks condenses the output, allowing you to instantly determine whether an enterprise NIC or storage controller attaches to the CPU socket hosting your primary database application.