Registry / ai-ml / nvidia-nccl-cu12

nvidia-nccl-cu12

JSON →
library2.29.7pypypiunverified

nvidia-nccl-cu12 (version 2.29.7) is the Python package providing the NVIDIA Collective Communication Library (NCCL) runtime specifically built for CUDA 12.x. NCCL is a foundational library for high-performance inter-GPU and inter-node communication primitives, such as all-reduce, all-gather, broadcast, and point-to-point operations, crucial for accelerating distributed deep learning workloads. It features a rapid release cadence, often synchronized with CUDA toolkit and major deep learning framework updates.

ai-mlaws
pip install nvidia-nccl-cu12
Install & Compatibility
Where this runs
tested against v2.30.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ no_wheel
9/10 runs
py 3.11
✕ no_wheel
9/10 runs
py 3.12
✕ no_wheel
9/10 runs
py 3.13
✕ no_wheel
9/10 runs
py 3.9
✕ no_wheel
4/10 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

NcclCommunicator
from nvidia.ncccl import NcclCommunicator
from nvidia.ncccl import NcclCommunicator

This quickstart demonstrates how NCCL is typically used indirectly via PyTorch's `torch.distributed` module for multi-GPU collective communication, specifically an `all_reduce` operation. NCCL provides the underlying high-performance backend. A proper distributed launcher (e.g., `torch.distributed.launch` or `mpirun`) is required to run this code across multiple processes/GPUs. For direct Python bindings, consider `nccl4py` for explicit NCCL API calls.

import os import torch import torch.distributed as dist # This quickstart assumes a multi-process setup, typically launched # via torch.distributed.launch or mpirun, where each process # runs this script with a unique rank and world_size. # Example environment variables (set by launch utility): # os.environ['MASTER_ADDR'] = os.environ.get('MASTER_ADDR', 'localhost') # os.environ['MASTER_PORT'] = os.environ.get('MASTER_PORT', '29500') # os.environ['RANK'] = os.environ.get('RANK', '0') # os.environ['WORLD_SIZE'] = os.environ.get('WORLD_SIZE', '1') def run_distributed_example(rank, world_size): # Initialize the process group with NCCL backend print(f"Initializing process group for rank {rank}/{world_size-1}...") dist.init_process_group(backend='nccl', rank=rank, world_size=world_size) print(f"Process group initialized on rank {rank}.") # Set device for the current process torch.cuda.set_device(rank) # Create a tensor on the GPU tensor = torch.ones(10, device=f'cuda:{rank}') * (rank + 1) print(f"Rank {rank}: Initial tensor value: {tensor}") # Perform an all_reduce operation (summing tensors across all GPUs) dist.all_reduce(tensor, op=dist.ReduceOp.SUM) print(f"Rank {rank}: Tensor after all_reduce: {tensor}") # Clean up the process group dist.destroy_process_group() print(f"Rank {rank}: Process group destroyed.") # To run this, you would typically use: # python -m torch.distributed.launch --nproc_per_node=2 your_script.py # Or set environment variables and run: # MASTER_ADDR=localhost MASTER_PORT=29500 RANK=0 WORLD_SIZE=2 python your_script.py # MASTER_ADDR=localhost MASTER_PORT=29500 RANK=1 WORLD_SIZE=2 python your_script.py # For simplicity, if running as a single process for structural check: if __name__ == '__main__': # In a real scenario, rank and world_size would be provided by a launcher. # This block is for structural demonstration only and will not perform # actual distributed communication without a proper launcher. try: rank = int(os.environ.get('RANK', '0')) world_size = int(os.environ.get('WORLD_SIZE', '1')) if torch.cuda.is_available() and world_size > 0: run_distributed_example(rank, world_size) else: print("CUDA not available or world_size is 0. Cannot run distributed example.") except RuntimeError as e: print(f"Error initializing distributed environment: {e}. This often happens if not run with a proper distributed launcher like torch.distributed.launch.")
Debug
Known issues
breakingNCCL versions are tightly coupled with CUDA Toolkit versions and the CUDA version used to compile deep learning frameworks (like PyTorch or TensorFlow). Mismatches can lead to runtime errors, silent performance degradation, or unexpected behavior.
fix
Ensure that the `nvidia-nccl-cu12` package, your system's CUDA Toolkit, and the CUDA version used by your deep learning framework are all compatible. Consult the NVIDIA documentation or framework-specific guides for compatibility matrices. For PyTorch, `torch.cuda.is_available()` and `torch.version.cuda` can help verify. For `nccl4py`, use `pip install "nccl4py[cu12]"` to ensure correct CUDA 12 support.
affects: All versions
gotchaThe `nvidia-nccl-cu12` package itself primarily provides the `libnccl.so` shared library. Direct Python API calls are not exposed through this package. Instead, Python users interact with NCCL through higher-level libraries like `nccl4py` (official bindings) or as a backend to distributed training modules in frameworks like PyTorch (`torch.distributed`) or TensorFlow (`tf.distribute`).
fix
To use NCCL directly from Python, install and import `nccl4py`. If using with a deep learning framework, configure its distributed module to use the NCCL backend. Avoid `import nccl` for direct API calls, as this package is a runtime provider.
affects: All versions
gotchaConflicts can arise if multiple NCCL installations are present on the system (e.g., `nvidia-nccl-cu12` from PyPI, a system-wide `apt`/`dnf` installed NCCL, or one bundled with a deep learning framework). The linker's search path (`LD_LIBRARY_PATH`) can affect which `libnccl.so` is loaded, potentially leading to incorrect versions being used.
fix
Prefer using `nvidia-nccl-cu12` installed via pip for consistency within Python environments. If system-wide NCCL is necessary, carefully manage `LD_LIBRARY_PATH` to ensure the correct `libnccl.so` is prioritized. Frameworks like PyTorch often statically link NCCL, mitigating some of these issues, but custom builds might need `USE_SYSTEM_NCCL` flags.
affects: All versions
breakingThe `nccl4py[cu12]` package, while recommended for direct Python interaction with NCCL CUDA 12, may not always have pre-built wheels available for all Python versions, operating systems, or architectures on PyPI. This can lead to `ERROR: Could not find a version that satisfies the requirement` during installation.
fix
Verify the availability of `nccl4py[cu12]` for your specific Python version and OS on PyPI or the official `nccl4py` documentation. If pre-built wheels are not available, you might need to compile `nccl4py` from source (which requires a CUDA Toolkit installation and potentially other build dependencies) or consider using a deep learning framework's distributed module, which often bundles NCCL or manages its own bindings.
affects: All versions of `nccl4py` with `[cu12]` extra
breakingThe `nvidia-nccl-cu12` package is not directly available on the default PyPI.org repository. It is hosted on the NVIDIA Python Package Index, and attempting to install it without configuring this index will result in a build error indicating it's a "placeholder project".
fix
To install `nvidia-nccl-cu12`, you must first install `nvidia-pyindex` to configure the NVIDIA Python Package Index, or specify the NVIDIA index URL directly. For example: `pip install nvidia-pyindex && pip install nvidia-nccl-cu12`, or `pip install --extra-index-url https://pypi.ngc.nvidia.com nvidia-nccl-cu12`.
affects: All versions
Upgrade
Version history
2.30.7latest on PyPI
Audit
Dependencies
cuda-pythonrequiredOften used implicitly or explicitly for CUDA Python bindings, especially with nccl4py.
torchoptionalCommonly used as a backend for PyTorch's distributed training module (torch.distributed).
tensorflowoptionalCommonly used as a backend for TensorFlow's distributed strategies (tf.distribute).
Agent activity
81 hits · last 30 days
node
8
ahrefsbot
3
seranking-bot
3
Resources