Install & Compatibility
Where this runs
tested against v0.48.0 · 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.2s · import 0.000s · 972MB
441MB installed
● package 441MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UCXWorker
✓ from ucxx.core import UCXWorker
✗ from ucxx import UCXWorker
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())
Debug
Known issues
breakingIn v0.49.0, the numba-cuda runtime dependency was replaced with cuda-core. Code relying on numba-cuda integration may break.fixEnsure your code uses cuda-core and does not depend on numba-cuda internally. Update any direct imports from numba.cuda.
affects: >=0.49.0
breakingIn v0.47.0, CUDA 12.2+ became mandatory. Older CUDA 11.x installations are no longer supported.fixUpgrade to CUDA 12.2 or later. If you need CUDA 11, stay on ucxx-cu11 (or ucxx <0.47).
affects: >=0.47.0
deprecatedThe `ucp` module (from the early `ucx-py` package) is deprecated. Import from `ucxx` instead.fixReplace `import ucp` with `import ucxx` and adjust imports (e.g., `ucp.get_worker()` -> `ucxx.get_worker()`).
affects: all
gotchaPython 3.13.12+ introduced behavior changes that may cause hangs with Python future notifiers. Skipping future notifiers is now recommended.fixSet environment variable `UCXX_SKIP_PYTHON_FUTURE_NOTIFIER=1` or upgrade to ucxx v0.49.0+ which automatically handles this.
affects: >=0.49.0 with Python 3.13.12+
gotchaUCX_TLS environment variable must include 'cuda_copy' for GPU transfers; otherwise UCX may fall back to CPU-only communication.fixSet `UCX_TLS=tcp,cuda_copy` before importing ucxx. Also ensure `UCX_PROTO_ENABLE=y`.
affects: all
Upgrade
Version history
0.50.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
numarequiredUCX requires NUMA libraries (libnuma) at runtime for topology-aware communication.
cuda-core (>=12.2)requiredCUDA runtime and driver libraries are required for UCX CUDA support; replaced numba-cuda in v0.49.0.
cudf or cupyoptionalCommon integration with RAPIDS cuDF or CuPy for GPU arrays.