NCCL Cluster Visualizer

NCCL Cluster Visualizer

Draws a picture of your GPU cluster from an NCCL XML dump, showing either the PCIe and NUMA tree with NVLink links or the NVLink rings NCCL chose. It suits engineers who run multi-GPU training.

Made by nouamanetazi on Hugging Face. These notes are Mindket's, written from its Space page and README; the app's own files and license are on Hugging Face.

About

What it is: NCCL Cluster Visualizer is a Gradio app that turns an NCCL XML dump into a drawing of your GPU cluster. It accepts two dump types and tells them apart by the root element of the file. The repository bundles a pair of sample dumps captured on a machine with H100 GPUs.

Who it suits: Engineers who run distributed GPU jobs and want to see how their machines are wired and which paths NCCL picked.

Industry | Who uses it | How they use it | Example
Machine learning | Training engineers | Check how GPUs, NVLink and NVSwitch connect | A topology dump from a training node
Infrastructure | Cluster admins | Confirm which links and speeds NCCL chose | A graph dump after a slow run
Research | Systems researchers | Compare communication layouts between machines | Two nodes with different wiring
Education | Students of HPC | Learn what a multi-GPU node looks like inside | The bundled H100 dumps

If you do not use NCCL or multi-GPU machines, you can skip it.

Where to use it:

• A web browser, on the Space's page at Hugging Face
• Windows, macOS or Linux with Python, from a downloaded copy
• The machine that runs your NCCL job, where the dump files are made

Use case | Who | What they get back
Topology view | Cluster admins | A drawn tree of PCIe and NUMA parts, with green lines for NVLink toward NVSwitch
Ring and channel view | Training engineers | The NVLink rings and channels NCCL chose, with speeds and link types
Trying it out | Newcomers | A drawing from the example dumps in the repository

How to set it up:

• Python on your computer
• Python packages from requirements.txt, with Gradio 5.34.2
• Dump files from an NCCL run, or the two bundled examples

1. Install the Hugging Face hub package.
2. Download the Space with the hf command.
3. Move into the downloaded folder.
4. Install Gradio 5.34.2, then the requirements.
5. Start app.py.

pip install -U huggingface_hub
hf download nouamanetazi/nccl-cluster-visualizer --repo-type space --local-dir nccl-cluster-visualizer
cd nccl-cluster-visualizer
pip install gradio==5.34.2
pip install -r requirements.txt
python app.py

How to use it: Run your distributed script once with the settings below so NCCL writes two dump files. Then give the app one of the two files, nccl-topo.xml or nccl-graphs.xml.

NCCL_DEBUG=INFO NCCL_DEBUG_SUBSYS=INIT,GRAPH,NET \
NCCL_TOPO_DUMP_FILE=nccl-topo.xml \
NCCL_GRAPH_DUMP_FILE=nccl-graphs.xml \
  python your_distributed_script.py

Tool | What it does
nccl-topo.xml | The topology dump, which the app draws as a PCIe, NUMA and NVLink tree
nccl-graphs.xml | The graph dump, which the app draws as NVLink rings and channels

Example: You drop the bundled nccl-topo.xml into the app. It draws the PCIe and NUMA tree of the H100 node, with green lines for the NVLink edges that lead to the NVSwitch fabric.

For newcomers and experts: Start with the two example dumps so you can see a result before you make your own. A topology dump shows how the hardware is connected, and a graph dump shows the paths NCCL decided to use.

The app reads the root element to tell the dumps apart, system for topology and graphs for the graph dump. These come from the NCCL_TOPO_DUMP_FILE and NCCL_GRAPH_DUMP_FILE settings. The source says nothing about cluster size limits or speed, so test it on your own dumps.

NCCL writes an XML dump during a run
You drop the file into the app
The root element sets the dump type
The app draws the cluster schema

Good to know:

• Built with Gradio 5.34.2
• Two dump types are supported and detected by their root element
• License: mit
• Cost to run: none named
• Data it reaches: the NCCL dump files you give it
• Not for: files other than NCCL topology and graph dumps

On Hugging Face, 13 November 2026

• Likes: 1
• Built with: gradio
• License: mit

Links

• Space: https://huggingface.co/spaces/nouamanetazi/nccl-cluster-visualizer
• Files: https://huggingface.co/spaces/nouamanetazi/nccl-cluster-visualizer/tree/main

Try it

Open the Space in your browser, or copy it to your own Hugging Face account from its page. Nothing in this kit runs by itself.