Document PyPI installation

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

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=<CUDA version> 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 <https://docs.conda.io/projects/conda/en/latest/>`_.
+Conda
+~~~~~
+
+The following instructions assume you'll be using UCX-Py on a CUDA-enabled system and is in a `Conda environment <https://docs.conda.io/projects/conda/en/latest/>`_.
 
 
 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())"