{"id":9890,"library":"libucx-cu12","title":"UCX (Unified Communication X) for CUDA 12","description":"libucx-cu12 is a Python package that provides the Unified Communication X (UCX) C library, specifically compiled with CUDA 12 support, as a distributable wheel. UCX is a low-level, high-performance communication framework for HPC applications, enabling optimized data exchange between CPUs, GPUs, and network interfaces (e.g., InfiniBand, RoCE). This package serves as a backend dependency for Python bindings like `ucx-py` (now `ucxx`), allowing Python applications to leverage UCX capabilities. The current version available on PyPI is `1.19.0`, with upstream UCX having a frequent release cadence including point releases and release candidates.","status":"active","version":"1.19.0","language":"en","source_language":"en","source_url":"https://github.com/openucx/ucx","tags":["gpu","hpc","networking","cuda","rdma","communication"],"install":[{"cmd":"pip install libucx-cu12","lang":"bash","label":"Install libucx-cu12"},{"cmd":"pip install ucxx","lang":"bash","label":"Install Python Bindings (ucxx)"}],"dependencies":[],"imports":[{"note":"The `libucx-cu12` package primarily provides the compiled UCX C shared libraries. It does not expose direct Python modules or symbols for import. Python users interact with UCX through separate binding packages like `ucx-py` (now `ucxx`), which depend on `libucx-cu12` for the underlying C implementation.","symbol":"No direct Python imports from 'libucx_cu12'","correct":"# libucx-cu12 provides the C library. For Python bindings, install 'ucxx' and import from it:\nfrom ucxx import init, get_version_info"}],"quickstart":{"code":"import os\nimport subprocess\nimport sys\n\n# Ensure libucx-cu12 is installed (it provides the C library)\n# and then ucxx (for Python bindings)\ntry:\n    import ucxx\n    print(f\"ucxx version: {ucxx.__version__}\")\n    print(f\"Underlying UCX version: {ucxx.get_version_info()}\")\n\n    # A simple UCX initialization example via ucxx\n    # Note: UCX often requires specific environment variables for optimal performance.\n    # For a basic test, default initialization might work.\n    # For distributed setup, UCP_RNDV_THRESH is often set.\n    # os.environ['UCX_TLS'] = 'rc_x,sm,self'\n    # os.environ['UCX_NET_DEVICES'] = 'mlx5_0:1' # Example for InfiniBand\n\n    # Initialize UCX context (from ucxx)\n    ctx = ucxx.init(enable_delayed_start=False)\n    print(\"UCX context initialized successfully via ucxx.\")\n    print(f\"UCX context info: {ctx}\")\n    # Additional UCX operations would follow here.\n    # For a complete example involving communication, see ucxx documentation.\n\nexcept ImportError:\n    print(\"Error: 'ucxx' not found. Please install it after 'libucx-cu12'.\")\n    print(\"Run: pip install ucxx\")\nexcept Exception as e:\n    print(f\"An error occurred during UCX initialization: {e}\")\n    print(\"Please check UCX environment variables and system dependencies (e.g., CUDA drivers).\")\n\n# You can also verify the installed UCX library version directly from the command line\n# This would typically be from the C library provided by libucx-cu12\nprint(\"\\nVerifying UCX shared library version (if ucx_info is in PATH):\")\ntry:\n    # This might not always be in PATH depending on how libucx-cu12 is installed.\n    # For wheels, it typically installs to site-packages, not system PATH.\n    # However, ucxx.get_version_info() above is the primary way.\n    result = subprocess.run(['ucx_info', '-v'], capture_output=True, text=True, check=True)\n    print(result.stdout)\nexcept FileNotFoundError:\n    print(\"`ucx_info` command not found. This is normal if UCX is only installed via Python wheels.\")\n    print(\"The `ucxx.get_version_info()` call above is the recommended way to check.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running ucx_info: {e}\\n{e.stderr}\")","lang":"python","description":"Install `libucx-cu12` to provide the CUDA 12-enabled UCX shared libraries. Then, install `ucxx` to get the Python bindings and verify UCX functionality and its underlying version. The example demonstrates basic initialization through `ucxx`."},"warnings":[{"fix":"Refer to the `ucxx` documentation for the version that wraps UCX 1.20.0+ to understand changes in GPU communication APIs.","message":"The upstream UCX 1.20.0 release introduced a new GPU device API for direct GPU-to-GPU communication and related host/device management. While `libucx-cu12` is currently at 1.19.0, users planning to upgrade to `libucx-cu12` versions based on UCX 1.20.0 or later should be aware that their `ucxx` code interacting with GPU communication might need updates.","severity":"breaking","affected_versions":"UCX 1.20.0 and later (when corresponding `libucx-cu12` wheels are released)."},{"fix":"Ensure your system's CUDA toolkit and driver version are compatible with CUDA 12.x. Check `nvidia-smi` output and CUDA installation paths.","message":"`libucx-cu12` is specifically built against CUDA 12.x. Using it with significantly older or newer CUDA runtime versions on the system (e.g., CUDA 11.x or 13.x+) can lead to runtime errors or undefined behavior, as the underlying C libraries depend on specific CUDA ABI compatibility.","severity":"gotcha","affected_versions":"All `libucx-cu12` versions."},{"fix":"Consult the official UCX documentation (and `ucx-py`/`ucxx` docs) for recommended environment variables based on your hardware and network configuration.","message":"UCX is a highly configurable library. Optimal performance, especially in HPC environments with InfiniBand or specific network fabrics, often requires setting various environment variables (e.g., `UCX_TLS`, `UCX_NET_DEVICES`, `UCX_MEMTYPE_CACHE_SIZE`). Default settings may not utilize hardware optimally.","severity":"gotcha","affected_versions":"All versions."},{"fix":"After installing `libucx-cu12`, run `pip install ucxx` to get the Python API.","message":"`libucx-cu12` provides the compiled UCX C library. To use it in Python, you *must* install a separate Python binding package, typically `ucx-py` (now `ucxx`). Installing `libucx-cu12` alone will not provide Python modules for import.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the Python bindings package: `pip install ucxx`.","cause":"The `libucx-cu12` package only provides the UCX C shared libraries; it does not include the Python bindings.","error":"ModuleNotFoundError: No module named 'ucxx'"},{"fix":"Verify `libucx-cu12` is installed (`pip show libucx-cu12`). If it is, check your `LD_LIBRARY_PATH` if you're managing libraries manually, or ensure `ucxx` is correctly installed to link against it. Reinstalling `libucx-cu12` and `ucxx` can often resolve this.","cause":"The UCX shared libraries, which `libucx-cu12` is meant to provide, are not found by the system's dynamic linker or by the `ucxx` bindings during initialization. This could be due to an incomplete `libucx-cu12` installation, `LD_LIBRARY_PATH` issues, or other environment problems.","error":"ImportError: libucx.so: cannot open shared object file: No such file or directory"},{"fix":"Ensure your system has CUDA 12.x installed and configured correctly, and that your GPU drivers support CUDA 12.x. Check `nvidia-smi` output for driver/CUDA version compatibility.","cause":"`libucx-cu12` is compiled for CUDA 12.x. The system's active CUDA runtime environment or GPU driver might be incompatible (e.g., an older CUDA 11.x or a very new 13.x/14.x with ABI changes).","error":"CUDA_ERROR_UNSUPPORTED_CPU_ARCHITECTURE"},{"fix":"Verify network interface drivers are installed and healthy (`ibdev2netdev` for InfiniBand). Check `UCX_NET_DEVICES` environment variable for correct device names. Ensure the user has appropriate permissions to access the network devices.","cause":"UCX cannot detect or initialize the specified network interfaces (e.g., InfiniBand devices). This can be due to missing drivers, incorrect device names in `UCX_NET_DEVICES`, or insufficient permissions.","error":"UCX_ERROR : Failed to get network devices"}]}