diff --git a/docker/ucx-py-cuda11.5.yml b/docker/ucx-py-cuda11.5.yml index 9e82f34b..39c08700 100644 --- a/docker/ucx-py-cuda11.5.yml +++ b/docker/ucx-py-cuda11.5.yml @@ -7,7 +7,7 @@ dependencies: - python=3.9 - cudatoolkit=11.5 - setuptools - - cython>=0.29.14,<3.0.0a0 + - cython>=3.0.0 - pytest - pytest-asyncio - dask diff --git a/docs/source/install.rst b/docs/source/install.rst index ac3038f5..b8712828 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -46,15 +46,40 @@ be done if desired (e.g., to test for new capabilities or bug fixes). conda create -n ucx -c conda-forge -c rapidsai \ cudatoolkit= ucx-py +PyPI +---- + +PyPI installation is possible and currently supports two variants: CUDA +version ``11`` and ``12``. Both packages are compatible with CPU-only +workloads and either one can be chosen if the application doesn't use +CUDA, but currently there are no pre-built CPU-only packages available, +so either one of CUDA packages must be installed instead. The CUDA +version is differentiated by the suffix ``-cuXY``, where ``XY`` must be +replaced with the desired CUDA version. Installing CUDA ``12`` package +can be done with the following command: + +:: + + pip install ucx-py-cu12 + + +UCX-Py has no direct dependency on CUDA, but the package specifies the +``-cuXY`` prefix so that the correct ``libucx-cuXY`` package is selected. +This is also the reason why there are no CPU-only UCX-Py packages +available at the moment, CPU-only builds of the UCX library are not +currently available in PyPI. Source ------ -The following instructions assume you'll be using UCX-Py on a CUDA enabled system and is in a `Conda environment `_. +Conda +~~~~~ + +The following instructions assume you'll be using UCX-Py on a CUDA-enabled system and is in a `Conda environment `_. Build Dependencies -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ :: @@ -67,7 +92,7 @@ Build Dependencies only Python 3.9, 3.10, and 3.11. Test Dependencies -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ :: @@ -78,7 +103,7 @@ Test Dependencies UCX >= 1.11.1 -~~~~~~~~~~~~~ +^^^^^^^^^^^^^ Instructions for building UCX >= 1.11.1 (minimum version supported by UCX-Py), make sure to change ``git checkout v1.11.1`` to a newer version if desired: @@ -99,7 +124,7 @@ Instructions for building UCX >= 1.11.1 (minimum version supported by UCX-Py), m UCX + rdma-core -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ It is possible to enable InfiniBand support via the conda-forge rdma-core package. To do so, first activate the environment created previously and install conda-forge compilers and rdma-core: @@ -127,7 +152,7 @@ After installing the necessary dependencies, it's now time to build UCX from sou UCX + MOFED -~~~~~~~~~~~ +^^^^^^^^^^^ It is still possible to build UCX and use the MOFED system install. Unlike the case above, we must not install conda-forge compilers, this is because conda-forge compilers can't look for libraries in the system directories (e.g., ``/usr``). Additionally, the rdma-core conda-forge package @@ -161,9 +186,32 @@ to adjust that for the path to your system compilers. For example: UCX-Py -~~~~~~ +^^^^^^ + +Building and installing UCX-Py can be done via ``pip install``. For example: + +:: + + conda activate ucx + git clone https://github.com/rapidsai/ucx-py.git + cd ucx-py + pip install -v . + # or for develop build + pip install -v -e . + + +PyPI +~~~~ + +The following instructions assume you'll be installing UCX-Py on a CUDA-enabled system, in a pip-only environment. + +Installing UCX-Py from source in a pip-only environment has additional limitations when compared to conda environments. Unlike conda packages, where the ``ucx`` package is installed under the ``CONDA_PREFIX``, ``libucx`` is installed under ``site-packages`` which is normally not looked for system libraries. Therefore, you will either need UCX to be installed in the system path, or include the UCX install path in ``LD_LIBRARY_PATH``. + + +UCX-Py with UCX system install +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Building and installing UCX-Py can be done via `pip install`. For example: +If a UCX system install is available, building and installing UCX-Py can be done via ``pip install`` with no additional requirements. For example: :: @@ -173,3 +221,40 @@ Building and installing UCX-Py can be done via `pip install`. For example: pip install -v . # or for develop build pip install -v -e . + + +UCX-Py with custom UCX install +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If UCX is installed in a non-default path, specifying ``LD_LIBRARY_PATH`` is required both to install and run UCX-Py code. For installation, ``LD_LIBRARY_PATH`` is required to ensure UCX-Py builds against the desired version of UCX, since another incompatible UCX version may already be installed in the system. Running UCX-Py code also needs to find the proper UCX libraries at runtime, and thus ``LD_LIBRARY_PATH`` must be specified as well. + +A custom UCX install does not necessarily mean it needs to be build from source, a ``libucx-cuXY`` package may be used as well. For example, with the CUDA ``12`` package: + +:: + + pip install libucx-cu12 + +The above will install the UCX library in your environment, specifically under ``site-packages/libucx``. To find the path to ``site-packages`` you may execute: + +:: + + python -c "import site; print(site.getsitepackages()[0])" + +The command above will print the path to ``site-packages``, such as ``/opt/python/site-packages``. The path to the UCX shared library installation is then ``/opt/python/site-packages/libucx/lib``, which is the value that will be specified for ``LD_LIBRARY_PATH``. If you build UCX from source and installed it in a different location, make sure you adjust the value of ``LD_LIBRARY_PATH`` accordingly, or if you built UCX from source and installed it in a path that the system will lookup for libraries by default, specifying ``LD_LIBRARY_PATH`` is unnecessary. + +Now installing UCX-Py can be done via ``pip install``: + +:: + + conda activate ucx + git clone https://github.com/rapidsai/ucx-py.git + cd ucx-py + LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib pip install -v . + # or for develop build + LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib pip install -v -e . + +Now, to run UCX-Py-enabled code specifying ``LD_LIBRARY_PATH`` will also be required. For example: + +:: + + LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib python -c "import ucp; print(ucp.get_ucx_version())"