{"id":23182,"library":"ucxx-cu12","title":"ucxx (CUDA 12)","description":"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+).","status":"active","version":"0.49.0","language":"python","source_language":"en","source_url":"https://github.com/rapidsai/ucxx","tags":["ucx","cuda","gpu","communication","rapids","distributed"],"install":[{"cmd":"pip install ucxx-cu12","lang":"bash","label":"Install from PyPI"},{"cmd":"conda install -c rapidsai -c conda-forge ucxx-cu12","lang":"bash","label":"Install from conda"}],"dependencies":[{"reason":"UCX requires NUMA libraries (libnuma) at runtime for topology-aware communication.","package":"numa","optional":false},{"reason":"CUDA runtime and driver libraries are required for UCX CUDA support; replaced numba-cuda in v0.49.0.","package":"cuda-core (>=12.2)","optional":false},{"reason":"Common integration with RAPIDS cuDF or CuPy for GPU arrays.","package":"cudf or cupy","optional":true}],"imports":[{"note":"In earlier versions (pre-0.30) the package was called `ucp`. Now it's `ucxx`.","wrong":"from ucp import UCXWorker","symbol":"UCXWorker","correct":"from ucxx import UCXWorker"},{"note":"","wrong":"","symbol":"UCXListener","correct":"from ucxx import UCXListener"},{"note":"This function lives in dask-cuda, not directly in ucxx.","wrong":"from ucxx import get_ucx_worker","symbol":"get_ucx_worker","correct":"from dask_cuda import get_ucx_worker"}],"quickstart":{"code":"import os\n# Set environment variables for UCX (optional but recommended)\nos.environ.setdefault('UCX_PROTO_ENABLE', 'y')\nos.environ.setdefault('UCX_TLS', 'tcp,cuda_copy')\n\nfrom ucxx import UCXListener, UCXWorker, get_config\n\n# Print UCX configuration to verify the environment\nprint(get_config())","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your code uses cuda-core and does not depend on numba-cuda internally. Update any direct imports from numba.cuda.","message":"In v0.49.0, the numba-cuda runtime dependency was replaced with cuda-core. Code relying on numba-cuda integration may break.","severity":"breaking","affected_versions":">=0.49.0"},{"fix":"Upgrade to CUDA 12.2 or later. If you need CUDA 11, stay on ucxx-cu11 (or ucxx <0.47).","message":"In v0.47.0, CUDA 12.2+ became mandatory. Older CUDA 11.x installations are no longer supported.","severity":"breaking","affected_versions":">=0.47.0"},{"fix":"Replace `import ucp` with `import ucxx` and adjust imports (e.g., `ucp.get_worker()` -> `ucxx.get_worker()`).","message":"The `ucp` module (from the early `ucx-py` package) is deprecated. Import from `ucxx` instead.","severity":"deprecated","affected_versions":"all"},{"fix":"Set environment variable `UCXX_SKIP_PYTHON_FUTURE_NOTIFIER=1` or upgrade to ucxx v0.49.0+ which automatically handles this.","message":"Python 3.13.12+ introduced behavior changes that may cause hangs with Python future notifiers. Skipping future notifiers is now recommended.","severity":"gotcha","affected_versions":">=0.49.0 with Python 3.13.12+"},{"fix":"Set `UCX_TLS=tcp,cuda_copy` before importing ucxx. Also ensure `UCX_PROTO_ENABLE=y`.","message":"UCX_TLS environment variable must include 'cuda_copy' for GPU transfers; otherwise UCX may fall back to CPU-only communication.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install `ucxx-cu12` and change imports to `import ucxx`.","cause":"Old code imports `ucp` but the package is now named `ucxx`.","error":"ModuleNotFoundError: No module named 'ucp'"},{"fix":"Install libnuma (e.g., `apt-get install libnuma-dev` on Ubuntu, or via conda `conda install -c conda-forge libnuma`).","cause":"UCX requires NUMA library at runtime.","error":"RuntimeError: libnuma.so.1: cannot open shared object file"},{"fix":"Upgrade CUDA to 12.2+ and update the driver. Check `nvidia-smi` for driver version.","cause":"CUDA 12.2+ is required but older CUDA is detected (error 803 usually indicates driver version mismatch).","error":"Error: UCX initialization failed: Cuda error: 803"},{"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.","cause":"CUDA support not compiled into UCX or missing GPU.","error":"ucxx.exceptions.UCXError: 'UCX_TLS' contains invalid transport 'cuda_copy'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}