Install & Compatibility
Where this runs
tested against v1.19.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
py 3.10
✕ build_error
2/4 runs
py 3.11
✕ build_error
2/4 runs
py 3.12
✕ build_error
2/4 runs
py 3.13
✕ build_error
2/4 runs
py 3.9
✕ build_error
2/4 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
No direct Python imports from 'libucx_cu12'
✓ # libucx-cu12 provides the C library. For Python bindings, install 'ucxx' and import from it:
from ucxx import init, get_version_info
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.
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`.
import os
import subprocess
import sys
# Ensure libucx-cu12 is installed (it provides the C library)
# and then ucxx (for Python bindings)
try:
import ucxx
print(f"ucxx version: {ucxx.__version__}")
print(f"Underlying UCX version: {ucxx.get_version_info()}")
# A simple UCX initialization example via ucxx
# Note: UCX often requires specific environment variables for optimal performance.
# For a basic test, default initialization might work.
# For distributed setup, UCP_RNDV_THRESH is often set.
# os.environ['UCX_TLS'] = 'rc_x,sm,self'
# os.environ['UCX_NET_DEVICES'] = 'mlx5_0:1' # Example for InfiniBand
# Initialize UCX context (from ucxx)
ctx = ucxx.init(enable_delayed_start=False)
print("UCX context initialized successfully via ucxx.")
print(f"UCX context info: {ctx}")
# Additional UCX operations would follow here.
# For a complete example involving communication, see ucxx documentation.
except ImportError:
print("Error: 'ucxx' not found. Please install it after 'libucx-cu12'.")
print("Run: pip install ucxx")
except Exception as e:
print(f"An error occurred during UCX initialization: {e}")
print("Please check UCX environment variables and system dependencies (e.g., CUDA drivers).")
# You can also verify the installed UCX library version directly from the command line
# This would typically be from the C library provided by libucx-cu12
print("\nVerifying UCX shared library version (if ucx_info is in PATH):")
try:
# This might not always be in PATH depending on how libucx-cu12 is installed.
# For wheels, it typically installs to site-packages, not system PATH.
# However, ucxx.get_version_info() above is the primary way.
result = subprocess.run(['ucx_info', '-v'], capture_output=True, text=True, check=True)
print(result.stdout)
except FileNotFoundError:
print("`ucx_info` command not found. This is normal if UCX is only installed via Python wheels.")
print("The `ucxx.get_version_info()` call above is the recommended way to check.")
except subprocess.CalledProcessError as e:
print(f"Error running ucx_info: {e}\n{e.stderr}")
Debug
Known issues
breakingThe 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.fixRefer to the `ucxx` documentation for the version that wraps UCX 1.20.0+ to understand changes in GPU communication APIs.
affects: UCX 1.20.0 and later (when corresponding `libucx-cu12` wheels are released).
gotcha`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.fixEnsure your system's CUDA toolkit and driver version are compatible with CUDA 12.x. Check `nvidia-smi` output and CUDA installation paths.
affects: All `libucx-cu12` versions.
gotchaUCX 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.fixConsult the official UCX documentation (and `ucx-py`/`ucxx` docs) for recommended environment variables based on your hardware and network configuration.
affects: All versions.
gotcha`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.fixAfter installing `libucx-cu12`, run `pip install ucxx` to get the Python API.
affects: All versions.
Upgrade
Version history
1.19.0latest on PyPI · released Sep 15, 2025
Audit
Dependencies
No dependency data recorded yet.