ucxx (CUDA 12)

0.49.0 verified Fri May 01 auth: no python

Python bindings for the Unified Communication X library (UCX), optimized for CUDA 12 memory operations (e.g., UCX_CUDA_COPY_ASYNC). Version 0.49.0 is current. Release cadence: aligns with RAPIDS releases (~monthly). This package replaces `ucxx` for systems with CUDA 12.x (requires CUDA 12.2+).

pip install ucxx-cu12

Common errors

error ModuleNotFoundError: No module named 'ucp' ↓

cause Old code imports `ucp` but the package is now named `ucxx`.

fix

Install ucxx-cu12 and change imports to import ucxx.

error RuntimeError: libnuma.so.1: cannot open shared object file ↓

cause UCX requires NUMA library at runtime.

fix

Install libnuma (e.g., apt-get install libnuma-dev on Ubuntu, or via conda conda install -c conda-forge libnuma).

error Error: UCX initialization failed: Cuda error: 803 ↓

cause CUDA 12.2+ is required but older CUDA is detected (error 803 usually indicates driver version mismatch).

fix

Upgrade CUDA to 12.2+ and update the driver. Check nvidia-smi for driver version.

error ucxx.exceptions.UCXError: 'UCX_TLS' contains invalid transport 'cuda_copy' ↓

cause CUDA support not compiled into UCX or missing GPU.

fix

Ensure you have a GPU with CUDA 12.2+ and install the ucxx-cu12 package (the conda variant includes CUDA support). Alternatively, remove 'cuda_copy' from UCX_TLS.

Warnings

breaking In v0.49.0, the numba-cuda runtime dependency was replaced with cuda-core. Code relying on numba-cuda integration may break. ↓

fix Ensure your code uses cuda-core and does not depend on numba-cuda internally. Update any direct imports from numba.cuda.

breaking In v0.47.0, CUDA 12.2+ became mandatory. Older CUDA 11.x installations are no longer supported. ↓

fix Upgrade to CUDA 12.2 or later. If you need CUDA 11, stay on ucxx-cu11 (or ucxx <0.47).

deprecated The `ucp` module (from the early `ucx-py` package) is deprecated. Import from `ucxx` instead. ↓

fix Replace `import ucp` with `import ucxx` and adjust imports (e.g., `ucp.get_worker()` -> `ucxx.get_worker()`).

gotcha Python 3.13.12+ introduced behavior changes that may cause hangs with Python future notifiers. Skipping future notifiers is now recommended. ↓

fix Set environment variable `UCXX_SKIP_PYTHON_FUTURE_NOTIFIER=1` or upgrade to ucxx v0.49.0+ which automatically handles this.

gotcha UCX_TLS environment variable must include 'cuda_copy' for GPU transfers; otherwise UCX may fall back to CPU-only communication. ↓

fix Set `UCX_TLS=tcp,cuda_copy` before importing ucxx. Also ensure `UCX_PROTO_ENABLE=y`.

Install

conda install -c rapidsai -c conda-forge ucxx-cu12

Imports

UCXWorker
wrong
```
from ucp import UCXWorker
```
correct
```
from ucxx import UCXWorker
```
In earlier versions (pre-0.30) the package was called `ucp`. Now it's `ucxx`.
UCXListener
```
from ucxx import UCXListener
```
get_ucx_worker
wrong
```
from ucxx import get_ucx_worker
```
correct
```
from dask_cuda import get_ucx_worker
```
This function lives in dask-cuda, not directly in ucxx.

Quickstart

Basic import and environment setup. Always set UCX_TLS to include 'cuda_copy' for GPU transfers. Use `os.environ.setdefault` to avoid overriding user settings.

import os
# Set environment variables for UCX (optional but recommended)
os.environ.setdefault('UCX_PROTO_ENABLE', 'y')
os.environ.setdefault('UCX_TLS', 'tcp,cuda_copy')

from ucxx import UCXListener, UCXWorker, get_config

# Print UCX configuration to verify the environment
print(get_config())