dcgmi topo#

NAME#

dcgmi-topo - display GPU topology and CPU affinity

SYNOPSIS#

dcgmi topo [--group <group-id>] [--json] [--host <address>]
dcgmi topo --gpuid <gpu-id> [--json] [--host <address>]

DESCRIPTION#

dcgmi topo reports CPU-core affinity and GPU interconnect paths. The GPU form describes paths from one GPU to the other reachable GPUs. The group form reports the CPU affinity, whether the group is NUMA-optimal, and its slowest interconnect path.

If neither target option is supplied, the command queries the built-in all-GPU group.

OPTIONS#

--gpuid <gpu-id>: Display topology for one GPU. Do not combine with --group.
-g <group-id>, --group <group-id>: Display topology for a persistent group. The default is the built-in all-GPU group.
-j, --json: Use JSON output. See JSON output.
--host <address>: Connect to the specified host engine.
-h, --help: Print generated usage information and exit.

OUTPUT INTERPRETATION#

For --gpuid, CPU Core Affinity is the formatted CPU-affinity mask for that GPU. Each To GPU <id> entry reports a PCIe relationship and, where present, a second line giving the number and local port IDs of direct NVLinks.

PCIe path text#
Output	Meaning
`Connected via an on-board PCIe switch`	The GPUs share a switch on the same board
`Connected via a single PCIe switch`	The path crosses one PCIe switch
`Connected via multiple PCIe switches`	The path crosses more than one PCIe switch
`Connected via a PCIe host bridge`	The path crosses a PCIe host bridge
`Connected via a CPU-level link`	The path crosses a CPU- or system-level interconnect; `dcgmi` renders both topology levels with the same text
`Unknown`	DCGM did not return a recognized PCIe path classification

For a group, CPU Core Affinity covers the group’s GPUs. NUMA Optimal is False when one or more GPUs have different CPU affinity, which can be suboptimal for algorithms that assume locality. Worst Path is the slowest PCIe relationship among the group’s GPU pairs; this summary does not print the per-pair NVLink port information available in the single-GPU form.

Topology is GPU-specific and can return Not Supported for a GPU or group. It describes connectivity; it does not reserve devices or bind a process to the reported CPU cores.

EXAMPLES#

Display topology for GPU 0:

$ dcgmi topo --gpuid 0

Display topology for group 1 as JSON:

$ dcgmi topo --group 1 --json