Install & Compatibility
Where this runs
tested against v3.7.2 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 0.000s · 371MB
368MB installed
● package 368MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nvshmem
✓ from nvidia import nvshmem
✗ import nvshmem.core as nvshmem
This quickstart demonstrates the basic initialization and finalization of NVSHMEM within a Python program using `nvshmem4py`. It also shows how to query the current PE (processing element) ID and the total number of PEs. Note that NVSHMEM operations are collective and require the script to be launched via a parallel environment, such as `mpiexec` (from MPI) or `nvshmrun` (provided with NVSHMEM), to correctly allocate and coordinate multiple PEs across GPUs. Running the script directly with `python` will lead to an error if not launched collectively.
import nvshmem.core as nvshmem
import os
def main():
# Initialize NVSHMEM. This is a collective operation.
# In a real scenario, this script would be launched with `mpiexec` or `nvshmrun`.
nvshmem.init()
# Query PE information
my_pe = nvshmem.my_pe()
n_pes = nvshmem.n_pes()
print(f"Hello from PE {my_pe} of {n_pes}")
# Perform some simple collective (e.g., a barrier)
# This ensures all PEs reach this point before proceeding
nvshmem.barrier_all()
# Finalize NVSHMEM. This is also a collective operation.
nvshmem.finalize()
if __name__ == '__main__':
# Note: This script needs to be run using an MPI launcher (e.g., mpiexec -n 2 python your_script.py)
# or NVSHMEM's own launcher (nvshmrun). Running directly 'python your_script.py'
# will result in an error or hang if NVSHMEM expects multiple processes.
try:
main()
except Exception as e:
# Catch potential errors if not launched collectively, for a more graceful exit
print(f"Error: {e}")
print("Please ensure the script is launched collectively, e.g., 'mpiexec -n 2 python quickstart.py'")
Debug
Known issues
breakingInternal layout changes in RC-connected Queue Pairs (QPs) starting in NVSHMEM 3.5.19 caused ABI compatibility breakage when enabling InfiniBand GPUDirect Async (IBGDA). This affects custom builds or specific configurations leveraging IBGDA.fixUsers enabling IBGDA should review NVSHMEM release notes for compatibility or rebuild applications against the specific NVSHMEM version they are using. Upgrading NVSHMEM may require recompiling dependent libraries.
affects: >=3.5.19
gotchaNVSHMEM (including its device-side APIs) and libraries that utilize NVSHMEM can typically only be built and linked as static libraries. This is due to limitations in how CUDA device symbols are linked across shared libraries, which is not supported.fixWhen building applications that use NVSHMEM, ensure that NVSHMEM components are linked statically. Avoid attempts to link `libnvshmem.so` as a shared library if encountered in lower-level C/C++ development.
affects: All versions
gotchaPrior to CUDA driver versions 460.106.00 (or later 470+), NVSHMEM might not be able to allocate the complete device memory due to issues with reusing BAR1 space. This can lead to memory allocation failures or unexpected behavior.fixEnsure your NVIDIA GPU drivers are updated to version 460.106.00 or later (or 470+ for the 460 branch) to resolve BAR1 memory allocation issues.
affects: <460.106.00 (or <470 for older branches)
gotchaNVSHMEM is not officially supported in virtualized environments (VMs). Using it in such environments may lead to unexpected behavior, performance degradation, or outright failures.fixRun NVSHMEM applications on bare-metal systems for full support and expected behavior.
affects: All versions
gotchaWhen `pip install nvidia-nvshmem-cu12` needs to compile Cython source code (e.g., if a pre-built wheel is not available), the CUDA runtime API headers must be accessible in the compiler's include path. Failure to do so results in compilation errors like 'Failed building wheel for nvshmem4py-cu12'.fixSet environment variables like `CPATH` or `CPPFLAGS` to include your CUDA toolkit's include directory (e.g., `-I/usr/local/cuda/include`) before running `pip install`.
affects: All versions (during installation/build)
deprecatedSupport for the active set-based collectives interface in OpenSHMEM has been removed. Older applications relying on this interface will no longer function as expected.fixMigrate applications to use team-based collectives (e.g., `NVSHMEM_TEAM_WORLD`) as per the current OpenSHMEM specification and NVSHMEM best practices.
affects: >=3.0.0 (removed in an earlier major release)
gotchaInstalling `nvidia-nvshmem-cu12` may fail with 'No matching distribution found' because pre-built wheels for the package are not available on PyPI for the specific Python version (e.g., 3.13) or operating system/architecture (e.g., Alpine Linux). NVIDIA NVSHMEM wheels are typically compiled against specific Python and CUDA versions and may not be immediately available for newly released Python versions or less common platforms.fixEnsure you are using a Python version and operating system for which `nvidia-nvshmem-cu12` wheels are officially published on PyPI. Check the official NVIDIA NVSHMEM documentation or PyPI project page for supported configurations. If no pre-built wheels are available, you may need to compile the package from source, if supported, which might require additional development dependencies.
affects: All versions (during installation with unsupported Python versions or platforms)
Upgrade
Version history
3.7.2latest on PyPI · released Jul 17, 2026
Audit
Dependencies
numpyrequiredRequired for array handling and interoperability.
cuda-pythonrequiredCUDA Python API for device interaction.
cuda.corerequiredCore CUDA Python utilities.
CythonrequiredRequired for building internal C++ accelerated Python bindings.
mpi4pyoptionalOptional, for MPI support and launching multi-PE applications.
cupyoptionalOptional, for interoperability with CuPy arrays.
torchoptionalOptional, for interoperability with PyTorch tensors.