Add optional tileiras dependency to pip install

- Update cupy example to use random API that doesn't depend on CTK

Signed-off-by: Jay Gu <jagu@nvidia.com>

Author: haijieg

README.md

@@ -31,8 +31,9 @@ def vector_add_kernel(a, b, result):
     ct.store(result, index=(block_id,), tile=result_tile)
 
 # Generate input arrays
-a = cupy.random.uniform(-5, 5, 128)
-b = cupy.random.uniform(-5, 5, 128)
+rng = cupy.random.default_rng()
+a = rng.random(128)
+b = rng.random(128)
 expected = cupy.asnumpy(a) + cupy.asnumpy(b)
 
 # Allocate an output array and launch the kernel

changelog.d/pip-install-with-tileiras.md

@@ -0,0 +1,4 @@
+<!--- SPDX-FileCopyrightText: Copyright (c) <2026> NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!--- SPDX-License-Identifier: Apache-2.0 -->
+
+- Support `pip install cuda-tile[tileiras]` to use `tileiras` from python environment instead of system-wide CTK installation.

docs/source/quickstart.rst

@@ -14,19 +14,34 @@ This page will guide you through getting setup and running with cuTile Python, i
 Prerequisites
 -------------------------------------------------------------------------------
 
-cuTile Python requires the following:   
+cuTile Python requires the following:
 
     - Linux x86_64, Linux aarch64 or Windows x86_64
-    - A GPU with compute capability 10.x or 12.x
+    - A GPU with compute capability 10.x, 11.x or 12.x
     - NVIDIA Driver r580 or later
-    - CUDA Toolkit 13.1 or later
     - Python version 3.10, 3.11, 3.12 or 3.13
 
 
 Installing cuTile Python
 -------------------------------------------------------------------------------
 
-With the :ref:`prerequisites <quickstart-prereqs>` met, installing cuTile Python is a simple pip install:
+cuTile Python depends on CUDA TileIR compiler ``tileiras``, which futher depends on ``ptxas`` and ``libnvvm``
+from the CUDA Toolkit.
+
+If your system does not have system-wide CUDA Toolkit (13.1+), you can install cuTile Python along with ``[tileiras]``,
+which installs ``nvidia-cuda-tileiras``, ``nvidia-cuda-nvcc`` and
+``nvidia-nvvm`` into your Python virtual environment.
+
+.. code-block::  bash
+
+    pip install cuda-tile[tileiras]
+
+Note: the package versions for ``nvidia-cuda-tileiras``, ``nvidia-cuda-nvcc`` and
+``nvidia-nvvm`` must match up to the same major.minor version.
+
+
+Alternatively if you already have system-wide CUDA Toolkit (13.1+) installed, you can install cuTile Python as a
+standalone package. cuTile automatically searches for ``tileiras`` from the location of CUDA Toolkit.
 
 .. code-block::  bash
 

pyproject.toml

@@ -37,6 +37,13 @@ dependencies = [
   "typing-extensions",
 ]
 
+[project.optional-dependencies]
+tileiras = [
+  "nvidia-cuda-tileiras>=13.2,<13.3",
+  "nvidia-cuda-nvcc>=13.2,<13.3",
+  "nvidia-nvvm>=13.2,<13.3",
+]
+
 [project.urls]
 Homepage = "https://github.com/nvidia/cutile-python"
 Repository = "https://github.com/nvidia/cutile-python"

samples/quickstart/VectorAdd_quickstart.py

@@ -34,8 +34,9 @@ def test():
     tile_size = 2**4
     grid = (ct.cdiv(vector_size, tile_size), 1, 1)
 
-    a = cp.random.uniform(-1, 1, vector_size)
-    b = cp.random.uniform(-1, 1, vector_size)
+    rng = cp.random.default_rng()
+    a = rng.random(vector_size)
+    b = rng.random(vector_size)
     c = cp.zeros_like(a)
 
     # Launch kernel

src/cuda/tile/_compile.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) <2025> NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
+import importlib.metadata
 import inspect
 import math
 import re
@@ -321,6 +322,7 @@ class _CompilerBinary:
     path: str
     bin_path: str
     ld_path: str
+    pass_cuda_home_var: bool
 
     def run(self,
             args: list[str],
@@ -335,6 +337,9 @@ def run(self,
             env = os.environ.copy()
             env['LD_LIBRARY_PATH'] = self.ld_path
             env['PATH'] = self.bin_path
+            if not self.pass_cuda_home_var:
+                for key in {"CUDA_HOME", "CUDA_PATH"}:
+                    env.pop(key, None)
             subprocess.run(command + flags, env=env, check=True, capture_output=True,
                            timeout=timeout_sec)
         except subprocess.CalledProcessError as e:
@@ -347,6 +352,54 @@ def run(self,
                                            _try_get_compiler_version(self.path))
 
 
+_PIP_TILEIRAS_PACKAGES = (
+    "nvidia-cuda-tileiras",
+    "nvidia-cuda-nvcc",
+    "nvidia-nvvm",
+)
+
+
+def _get_major_minor(version_str: str) -> tuple[int, int]:
+    parts = version_str.split(".")
+    return int(parts[0]), int(parts[1])
+
+
+def _find_pip_tileiras() -> Optional[str]:
+    versions: dict[str, str] = {}
+    for pkg in _PIP_TILEIRAS_PACKAGES:
+        try:
+            versions[pkg] = importlib.metadata.version(pkg)
+        except importlib.metadata.PackageNotFoundError:
+            return None
+
+    majors_minors = {pkg: _get_major_minor(v) for pkg, v in versions.items()}
+    unique = set(majors_minors.values())
+    if len(unique) != 1:
+        details = ", ".join(f"{pkg} {versions[pkg]}" for pkg in _PIP_TILEIRAS_PACKAGES)
+        warnings.warn(
+            f"Installed NVIDIA pip packages have mismatched versions ({details}). "
+            "Falling back to system tileiras.",
+            stacklevel=3,
+        )
+        return None
+
+    try:
+        import nvidia.cu13 as cu13_pkg
+        cu13_root = cu13_pkg.__path__[0]
+    except (ImportError, AttributeError, IndexError):
+        logger.debug("Fail to get nvidia.cu13 package path.", exc_info=True)
+        return None
+
+    pip_bin_dir = os.path.join(cu13_root, "bin")
+    res = shutil.which("tileiras", path=pip_bin_dir)
+    if res is None:
+        logger.debug("Fail to find tileiras under nvidia.cu13 path.")
+        return None
+
+    logger.debug(f"Found tileiras from pip package: {res}")
+    return res
+
+
 @cache
 def _find_compiler_bin() -> _CompilerBinary:
     # search under cuda/tile/_deps
@@ -360,30 +413,39 @@ def _find_compiler_bin() -> _CompilerBinary:
         if (res := shutil.which("tileiras", path=deps_bin_dir)):
             bin_path = deps_bin_dir + ":" + bin_path
             ld_path = deps_lib_dir + ":" + ld_path
-            return _CompilerBinary(res, bin_path, ld_path)
+            return _CompilerBinary(res, bin_path, ld_path, pass_cuda_home_var=False)
+
+    # search from nvidia-cuda-tileiras pip package
+    logger.debug("Searching tileiras from nvidia pip package")
+    res = _find_pip_tileiras()
+    if res is not None:
+        return _CompilerBinary(res, bin_path, ld_path, pass_cuda_home_var=False)
 
     # search under PATH
     logger.debug(f"Searching tileiras: {bin_path}")
     if (res := shutil.which("tileiras")):
-        return _CompilerBinary(res, bin_path, ld_path)
+        return _CompilerBinary(res, bin_path, ld_path, pass_cuda_home_var=True)
 
     # search under CUDA_HOME
     if (cuda_home := _get_cuda_home()):
         cuda_bin_path = os.path.join(cuda_home, 'bin')
         logger.debug(f"Searching tileiras: {cuda_bin_path}")
         if (res := shutil.which("tileiras", path=cuda_bin_path)):
             bin_path = bin_path + ":" + cuda_bin_path
-            return _CompilerBinary(res, bin_path, ld_path)
+            return _CompilerBinary(res, bin_path, ld_path, pass_cuda_home_var=True)
 
     # Try default CUDA Toolkit installation paths as a fallback
     res = _find_compiler_in_default_cuda_toolkit_paths()
     if res is not None:
         tileiras_path, bin_path = res
-        return _CompilerBinary(tileiras_path, bin_path, ld_path)
+        return _CompilerBinary(tileiras_path, bin_path, ld_path, pass_cuda_home_var=False)
 
     cuda_home_var = "CUDA_PATH" if is_windows() else "CUDA_HOME"
-    raise FileNotFoundError(f"'tileiras' compiler not found, "
-                            f"make sure it is available in $PATH or ${cuda_home_var}/bin")
+    raise FileNotFoundError("'tileiras' compiler not found, "
+                            "make sure it is available as a python package via "
+                            "`pip install cuda-tile[tileiras]` or "
+                            f"available in $PATH or ${cuda_home_var}/bin via system CTK (13.1+)"
+                            " installation.")
 
 
 @cache

test/test_frontpage_example.py

@@ -30,8 +30,9 @@ def vector_add(a: cupy.ndarray, b: cupy.ndarray, result: cupy.ndarray):
 import numpy as np
 
 def test_vector_add():
-    a = cupy.random.uniform(-5, 5, 128)
-    b = cupy.random.uniform(-5, 5, 128)
+    rng = cupy.random.default_rng()
+    a = rng.random(128)
+    b = rng.random(128)
     result = cupy.zeros_like(a)
 
     vector_add(a, b, result)
@@ -42,4 +43,3 @@ def test_vector_add():
 
     expected = a_np + b_np
     np.testing.assert_array_almost_equal(result_np, expected)
-