Install & Compatibility
Where this runs
tested against v0.3.1 · 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 9.6s · import 0.676s · 376MB
405MB installed
● package 405MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nvshmem
✓ import nvshmem.core as nvshmem
This quickstart demonstrates basic initialization, querying the Processing Element (PE) ID and total number of PEs, and finalization of the NVSHMEM environment. NVSHMEM is a multi-process library, so applications typically need to be launched with an MPI runner (e.g., `mpirun`).
import nvshmem.core as nvshmem
import os
def main():
# Initialize NVSHMEM environment
if not nvshmem.is_initialized():
nvshmem.init()
# Query current Processing Element (PE) ID and total number of PEs
my_pe = nvshmem.my_pe()
n_pes = nvshmem.n_pes()
print(f"Hello from PE {my_pe} of {n_pes}!")
# Finalize NVSHMEM environment
nvshmem.finalize()
if __name__ == "__main__":
# This example must be launched with an MPI runner, e.g.:
# mpirun -np 2 python your_script_name.py
main()
Debug
Known issues
gotchaInstallation issues due to missing CUDA runtime API headers. NVSHMEM4Py's internal bindings require the CUDA runtime API headers to be available in the compiler's include path during installation (e.g., via `CPPFLAGS` or `CPATH`).fixEnsure the CUDA toolkit's include directory is in your compiler's search path (e.g., `export CPPFLAGS="-I/usr/local/cuda/include"` or `export CPATH="/usr/local/cuda/include:$CPATH"` before pip installation).
affects: All versions
gotchaPotential hangs or errors from `nvshmem.core.finalize()` if symmetric memory buffers have multiple references and are not explicitly freed before finalization. The internal buffer tracking might not fully deallocate all resources if reference counts are above one, leading to issues if Python's garbage collector attempts to free them after NVSHMEM is finalized.fixExplicitly call `nvshmem.core.free_tensor(tensor_obj)` for all allocated symmetric tensors or buffers to ensure they are deallocated before `nvshmem.core.finalize()` is called. Consider upgrading to the latest version to benefit from potential fixes.
affects: Versions <= 0.2.1 (issue discussed and acknowledged, fix expected in later releases).
gotchaMisinterpretation of `nvshmem.core.rma.quiet` semantics: Older documentation incorrectly implied that `nvshmem.core.rma.quiet` guaranteed remote completion for RMA operations, similar to `shmem_quiet` in OpenSHMEM. In reality, it only ensures local completion; remote completion is guaranteed by a stream synchronization.fixRefer to the latest official documentation for `nvshmem.core.rma.quiet` and explicitly use CUDA stream synchronization primitives (e.g., `cudaStreamSynchronize`) or NVSHMEM's collective synchronization APIs for remote completion guarantees if needed.
affects: Documentation prior to fix in 0.3.0 release.
gotchaInfiniBand (IB) failures (Remote Protection Error / Local Protection Error) when using non-symmetric heap addresses. Attempting RMA or atomic operations on memory addresses not allocated via NVSHMEM's symmetric heap or not registered as local buffers will result in protection errors.fixEnsure all buffers used in NVSHMEM RMA or atomic operations are allocated using `nvshmem.malloc`, `nvshmem.calloc`, or explicitly registered with `nvshmemx_buffer_register_symmetric`.
affects: All versions
gotchaBlocking CUDA calls on stream 0 (e.g., `cudaDeviceSynchronize`, `cudaMemcpy`) in the iterative phase of an application can lead to hangs, particularly in NVSHMEM programs.fixAvoid blocking CUDA calls on the default stream (stream 0) within performance-critical loops. Use non-blocking operations and explicit stream synchronization (e.g., with `cudaStreamCreate` and `cudaStreamSynchronize` on specific streams) to manage dependencies.
affects: All versions
Upgrade
Version history
0.3.1latest on PyPI · released Jun 11, 2026
Audit
Dependencies
nvidia-nvshmem-cu13requiredProvides the underlying NVSHMEM C/C++ library for CUDA 13.x.
numpyrequiredInteroperability with NumPy arrays for symmetric memory management.
mpi4pyoptionalUsed for certain initialization methods (e.g., MPI Comm-based) and testing frameworks.
cupyoptionalSeamless interoperability and NVSHMEM operations with CuPy arrays and tensors.
torchoptionalSeamless interoperability and NVSHMEM operations with PyTorch tensors.
numba-cudaoptionalEnables writing fused compute-communication GPU kernels in Python using Numba's CUDA DSL.
tritonoptionalEnables interoperability with Triton-expressed GPU kernels.