How to use lstopo to visualize System Topology

2025-06-21 | UNIX | #Words: 892 | 中文原版

lstopo is an excellent tool for generating intuitive, concise system topology diagrams. This article documents small issues I encountered while using it—it is not a comprehensive manual. For detailed options, refer to the official documentation: lstopo(1) - Linux man page.

The term “topo” in lstopo stands for “topology” (referring to computer system topology).

Installation

Many Linux distributions come with hwloc preinstalled. If your system lacks it (e.g., Ubuntu), install it with:

sudo apt install hwloc

lstopo is responsible for visually displaying the topology detected by hwloc.

Alternatively, install it manually from Portable Hardware Locality (hwloc). Download from the “Sub-Projects” section, as highlighted in the red box below:

hwloc download page showing Sub-Projects section

To print a nicely formatted system topology directly in the terminal, use this simple command:

lstopo --of ascii -p

Parameter Explanations:

  • --of ascii: Specifies ASCII output (uses ASCII art—characters arranged to form a diagram). For example, here’s an ASCII art door:
Example of ASCII art door
  • -p: Prints physical IDs (labeled as P#; use -l for logical IDs labeled L#).

Sample Terminal Output:

lstopo ASCII output in terminal showing CPU caches, cores, and PCI devices

The output shows the CPU’s three-level cache, processing units within each core, and PCI devices.

Generate Image/File Formats

lstopo supports generating formats like PNG, JPG, SVG, PDF, and XML. Below is an example using SVG:

Sample SVG topology diagram generated by lstopo

Command to Generate SVG:

env LANG=zh_CN.UTF-8 lstopo --output-format svg > 1.svg

--output-format is the full name of the shorthand --of.

Key Note for Chinese Display:

The env LANG=zh_CN.UTF-8 prefix ensures Chinese characters render correctly (without it, Chinese text may appear as square boxes □):

Broken Chinese text (square boxes) without proper LANG setting

Simplified Command:

You can also use this shorter command to generate files (automatically detects format from the extension):

env LANG=zh_CN.UTF-8 lstopo 1.svg

Overwrite Existing Files:

Add the -f flag to force overwrite existing files:

env LANG=zh_CN.UTF-8 lstopo 1.svg -f

Other Formats:

Replace the file extension to generate other formats:

  • XML: env LANG=zh_CN.UTF-8 lstopo 1.xml
  • PNG: env LANG=zh_CN.UTF-8 lstopo 1.png -f

For all supported formats, see the “OUTPUT FORMATS” section in lstopo(1) - Linux man page.

Why did I show the longer --output-format command first? Many documents use it—likely for historical reasons. I prefer documenting multiple working methods; you never know when a specific scenario might require one over the other.

Important Note: PNG/JPG Quality Issues

PNG and JPG are common formats (e.g., for blog posts), but they tend to be blurry (not due to compression). Smaller images may look acceptable, but larger ones suffer from poor clarity:

Blurry PNG topology diagram

Solution: Use PDF as an Intermediate Format

To get clear images:

  1. Generate a PDF first.
  2. Convert the PDF to PNG/JPG.
PDF to image conversion workflow

The resulting image will be sharp:

Clear image converted from PDF

Why Not SVG as an Intermediate Format?

On macOS, converting SVG to images often results in empty files for unknown reasons:

Empty file after SVG to image conversion on macOS

Third-party tools can fix this, but I prefer using built-in utilities when possible.

I hope these will help someone in need~

References/Further Reading

  • ASCII Art Archive: An archive of ASCII art works. You may also encounter this style in comments on platforms like Douyin. A similar style called CACA Format will be covered in a future blog post.
  • Note: When searching for SVG-to-PNG tools, I discovered macOS’s built-in qlmanage (used for generating thumbnails). However, it produces square images, which may crop parts of the topology diagram.
  • lstopo(1) - Linux man page: Official lstopo manual with useful examples.
  • Hwloc tutorial: Official tutorial covering lstopo usage, library integration, and advanced features (for intermediate/advanced users).
  • Validate PCI Switch System Topology - NVIDIA Docs: NVIDIA’s guide to validating PCI switch topology, including a brief introduction to installing and using lstopo.