# nvidia/nccl architecture

> Architecture diagram of the GitHub repository nvidia/nccl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/nccl
- Repository: https://github.com/nvidia/nccl

## Overview

NCCL is a GPU collective-communication library. An application initializes a communicator and submits collective or point-to-point work; NCCL plans that work and executes it across GPUs using device kernels and available local or network transports. The graph also includes topology selection, memory management, remote-memory operations, and optional tuner, profiler, and RAS capabilities. Several implementation links are based on source-index references rather than complete call traces, so those links are dashed; the README supports the documented communication capabilities but not their internal wiring.

Main entry points: [`src/enqueue/enqueue.cc`](https://github.com/nvidia/nccl/blob/master/src/enqueue/enqueue.cc) (Work submission), [`src/include/comm.h`](https://github.com/nvidia/nccl/blob/master/src/include/comm.h) (Communicator state), [`src/transport.cc`](https://github.com/nvidia/nccl/blob/master/src/transport.cc) (Transport selection), [`src/include/core.h`](https://github.com/nvidia/nccl/blob/master/src/include/core.h) (NCCL API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["NCCL API<br/>[core.h]"]
  node_communicator["Communicator state<br/>[comm.h]"]
  node_enqueue["Work submission<br/>[enqueue.cc]"]
end

subgraph group_planning["Planning and scheduling"]
  node_topology["Topology search<br/>[search.cc]"]
  node_taskprep["Task preparation<br/>[task_posttuning.cc]"]
  node_scheduler["Task scheduling<br/>[task_sched.cc]"]
end

subgraph group_execution["Communication execution"]
  node_collectives["Collective operations<br/>[collectives.cc]"]
  node_devicekernels["GPU kernels<br/>[prims_simple.h]"]
  node_transport["Transport selection<br/>[transport.cc]"]
  node_network["Network transport<br/>[net.cc]"]
  node_proxy["Proxy progress<br/>[proxy.cc]"]
  node_rma["Remote memory<br/>[rma.cc]"]
end

subgraph group_resources["Resources and observability"]
  node_memory["Memory management<br/>[mem_manager.cc]"]
  node_contracts["Core contracts"]
end

subgraph group_extensions["Extensions and diagnostics"]
  node_tuner["Tuning plugins<br/>[tuner.cc]"]
  node_profiler["Profiler plugins<br/>[profiler.cc]"]
  node_inspector["Inspector plugin<br/>[inspector.cc]"]
  node_ras["RAS monitoring<br/>[client_support.cc]"]
end

node_application(("GPU application"))
node_networkuser[("Network fabric")]

node_application -->|"calls"| node_api
node_api -.->|"uses"| node_communicator
node_communicator -.->|"submits work"| node_enqueue
node_enqueue -.->|"prepares tasks"| node_taskprep
node_enqueue -.->|"uses topology"| node_topology
node_enqueue -->|"schedules work"| node_scheduler
node_taskprep -.->|"tunes tasks"| node_tuner
node_scheduler -.->|"dispatches work"| node_collectives
node_collectives -.->|"executes on GPU"| node_devicekernels
node_enqueue -->|"uses transport"| node_transport
node_transport -.->|"selects network"| node_network
node_network -.->|"transfers data"| node_networkuser
node_transport -.->|"uses progress"| node_proxy
node_enqueue -->|"dispatches RMA"| node_rma
node_communicator -->|"manages memory"| node_memory
node_enqueue -->|"reports activity"| node_profiler
node_profiler -->|"loads plugin"| node_inspector
node_communicator -.->|"reports status"| node_ras
node_communicator -->|"uses definitions"| node_contracts
node_transport -->|"uses interfaces"| node_contracts

click node_api "https://github.com/nvidia/nccl/blob/master/src/include/core.h"
click node_communicator "https://github.com/nvidia/nccl/blob/master/src/include/comm.h"
click node_enqueue "https://github.com/nvidia/nccl/blob/master/src/enqueue/enqueue.cc"
click node_topology "https://github.com/nvidia/nccl/blob/master/src/graph/search.cc"
click node_taskprep "https://github.com/nvidia/nccl/blob/master/src/enqueue/task_prep/task_posttuning.cc"
click node_scheduler "https://github.com/nvidia/nccl/blob/master/src/enqueue/task_sched/task_sched.cc"
click node_collectives "https://github.com/nvidia/nccl/blob/master/src/collectives.cc"
click node_devicekernels "https://github.com/nvidia/nccl/blob/master/src/device/prims_simple.h"
click node_transport "https://github.com/nvidia/nccl/blob/master/src/transport.cc"
click node_network "https://github.com/nvidia/nccl/blob/master/src/transport/net.cc"
click node_proxy "https://github.com/nvidia/nccl/blob/master/src/proxy.cc"
click node_rma "https://github.com/nvidia/nccl/blob/master/src/rma/rma.cc"
click node_memory "https://github.com/nvidia/nccl/blob/master/src/mem_manager.cc"
click node_contracts "https://github.com/nvidia/nccl/tree/master/src/include"
click node_tuner "https://github.com/nvidia/nccl/blob/master/src/plugin/tuner.cc"
click node_profiler "https://github.com/nvidia/nccl/blob/master/src/plugin/profiler.cc"
click node_inspector "https://github.com/nvidia/nccl/blob/master/plugins/profiler/inspector/inspector.cc"
click node_ras "https://github.com/nvidia/nccl/blob/master/src/ras/client_support.cc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_communicator,node_enqueue toneBlue
class node_topology,node_taskprep,node_scheduler,node_networkuser toneAmber
class node_collectives,node_devicekernels,node_transport,node_network,node_proxy,node_rma toneMint
class node_memory,node_contracts toneRose
class node_tuner,node_profiler,node_inspector,node_ras,node_application toneIndigo
```

## Components

### API and orchestration

- [NCCL API](https://github.com/nvidia/nccl/blob/master/src/include/core.h): `src/include/core.h`
- [Communicator state](https://github.com/nvidia/nccl/blob/master/src/include/comm.h): `src/include/comm.h`
- [Work submission](https://github.com/nvidia/nccl/blob/master/src/enqueue/enqueue.cc): `src/enqueue/enqueue.cc`

### Planning and scheduling

- [Topology search](https://github.com/nvidia/nccl/blob/master/src/graph/search.cc): `src/graph/search.cc`
- [Task preparation](https://github.com/nvidia/nccl/blob/master/src/enqueue/task_prep/task_posttuning.cc): `src/enqueue/task_prep/task_posttuning.cc`
- [Task scheduling](https://github.com/nvidia/nccl/blob/master/src/enqueue/task_sched/task_sched.cc): `src/enqueue/task_sched/task_sched.cc`

### Communication execution

- [Collective operations](https://github.com/nvidia/nccl/blob/master/src/collectives.cc): `src/collectives.cc`
- [GPU kernels](https://github.com/nvidia/nccl/blob/master/src/device/prims_simple.h): `src/device/prims_simple.h`
- [Transport selection](https://github.com/nvidia/nccl/blob/master/src/transport.cc): `src/transport.cc`
- [Network transport](https://github.com/nvidia/nccl/blob/master/src/transport/net.cc): `src/transport/net.cc`
- [Proxy progress](https://github.com/nvidia/nccl/blob/master/src/proxy.cc): `src/proxy.cc`
- [Remote memory](https://github.com/nvidia/nccl/blob/master/src/rma/rma.cc): `src/rma/rma.cc`

### Resources and observability

- [Memory management](https://github.com/nvidia/nccl/blob/master/src/mem_manager.cc): `src/mem_manager.cc`
- [Core contracts](https://github.com/nvidia/nccl/tree/master/src/include): `src/include`

### Extensions and diagnostics

- [Tuning plugins](https://github.com/nvidia/nccl/blob/master/src/plugin/tuner.cc): `src/plugin/tuner.cc`
- [Profiler plugins](https://github.com/nvidia/nccl/blob/master/src/plugin/profiler.cc): `src/plugin/profiler.cc`
- [Inspector plugin](https://github.com/nvidia/nccl/blob/master/plugins/profiler/inspector/inspector.cc): `plugins/profiler/inspector/inspector.cc`
- [RAS monitoring](https://github.com/nvidia/nccl/blob/master/src/ras/client_support.cc): `src/ras/client_support.cc`

### Other components

- **GPU application**
- **Network fabric**

## Connections

- GPU application → NCCL API: calls (evidence: `README.md`)
- NCCL API → Communicator state: uses
- Communicator state → Work submission: submits work
- Work submission → Task preparation: prepares tasks
- Work submission → Topology search: uses topology
- Work submission → Task scheduling: schedules work (evidence: `src/enqueue/enqueue.cc`)
- Task preparation → Tuning plugins: tunes tasks
- Task scheduling → Collective operations: dispatches work
- Collective operations → GPU kernels: executes on GPU
- Work submission → Transport selection: uses transport (evidence: `src/enqueue/enqueue.cc`)
- Transport selection → Network transport: selects network
- Network transport → Network fabric: transfers data
- Transport selection → Proxy progress: uses progress
- Work submission → Remote memory: dispatches RMA (evidence: `src/enqueue/enqueue.cc`)
- Communicator state → Memory management: manages memory (evidence: `src/mem_manager.cc`)
- Work submission → Profiler plugins: reports activity (evidence: `src/enqueue/enqueue.cc`)
- Profiler plugins → Inspector plugin: loads plugin (evidence: `src/plugin/profiler.cc`)
- Communicator state → RAS monitoring: reports status (evidence: `src/ras/client_support.cc`)
- Communicator state → Core contracts: uses definitions (evidence: `src/include/comm.h`)
- Transport selection → Core contracts: uses interfaces (evidence: `src/include/transport.h`)