.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 Installation ============ Runtime Requirements -------------------- ``cuda.core`` is supported on all platforms that CUDA is supported. Specific dependencies are as follows: .. list-table:: :header-rows: 1 * - - CUDA 12 - CUDA 13 * - CUDA Toolkit\ [#f1]_ - 12.x - 13.x * - Driver - 525.60.13+ (Linux), 527.41+ (Windows) - 580.65+ (Linux), 580.88+ (Windows) .. [#f1] Including ``cuda-python``. ``cuda.core`` supports Python 3.11 - 3.15, on Linux (x86-64, arm64) and Windows (x86-64). **Experimental** free-threaded builds for Python 3.14 and 3.15 are also provided. Free-threading Build Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting ``cuda-core`` 0.4.0, **experimental** packages for the `free-threaded interpreter`_ are shipped. 1. Support for these builds is best effort, due to heavy use of `built-in modules that are known to be thread-unsafe`_, such as ``ctypes``. 2. For now, you are responsible for making sure that calls into the ``cuda-core`` library are thread-safe. This is subject to change. .. _built-in modules that are known to be thread-unsafe: https://github.com/python/cpython/issues/116738 .. _free-threaded interpreter: https://docs.python.org/3/howto/free-threading-python.html Installing from PyPI -------------------- ``cuda.core`` works with ``cuda-bindings`` (part of ``cuda-python``) 12 or 13 at or above the release's floor for that major. See :ref:`cuda-core-bindings-floor`. The ``cu12`` and ``cu13`` extras install a compatible version. Test dependencies now use the ``cuda-toolkit`` metapackage for improved dependency resolution. For example with CUDA 12: .. code-block:: console $ pip install cuda-core[cu12] and likewise use ``[cu13]`` for CUDA 13. If you upgrade ``cuda-core`` alone, the installed ``cuda-bindings`` can be older than the new release requires. ``import cuda.core`` then reports the required version and the ``pip`` command that installs it. Installing from Conda (conda-forge) ----------------------------------- Same as above, ``cuda.core`` can be installed in a CUDA 12 or 13 environment. For example with CUDA 12: .. code-block:: console $ conda install -c conda-forge cuda-core cuda-version=12 and likewise use ``cuda-version=13`` for CUDA 13. The conda-forge package depends on ``cuda-bindings`` of the same CUDA major. The ``cuda-bindings`` floor of the release also applies to it. See :ref:`cuda-core-bindings-floor`. Development environment ----------------------- The sections below cover nightly builds, source installation, and repeatable development workflows with editable installs and tests. Installing the latest nightly (top-of-tree builds) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These are useful for users looking to test new features or bug fixes prior to their inclusion in a release. CI publishes wheels as GitHub Actions artifacts on every push to ``main``. To obtain the most recent build, use the following commands: .. code-block:: console $ # Find the latest successful CI run on main: $ RUN_ID=$(gh run list -R NVIDIA/cuda-python -w ci.yml -b main -s success -L1 --json databaseId -q '.[0].databaseId') $ # Download the wheel (pick your Python version and platform): $ gh run download "$RUN_ID" -R NVIDIA/cuda-python -p "cuda-core-python312-linux-64-*" $ # Install the downloaded wheel: $ pip install cuda-core-python312-linux-64-*/cuda_core*.whl[cu13] Replace ``python312`` with your Python version (e.g. ``python310``, ``python311``, ``python313``, ``python314``, ``python314t``). For aarch64, replace ``linux-64`` with ``linux-aarch64``; for Windows, use ``win-64``. Replace ``cu13`` with ``cu12`` for CUDA 12.x environments. .. _cuda-core-source-install: Installing from Source ~~~~~~~~~~~~~~~~~~~~~~ A source build has two requirements. See :ref:`cuda-core-bindings-floor`. - ``cuda-bindings`` 12.x or 13.x at or above the release's floor for that major. An isolated build, the default for ``pip install``, installs a ``cuda-bindings`` no newer than the toolkit's minor. Other builds must provide it. - A CUDA Toolkit, located through ``CUDA_PATH`` or ``CUDA_HOME``, whose ``cuda.h`` has the same major.minor as the header that ``cuda-bindings`` was generated from. If the versions differ, the build fails early. To build against a specific ``cuda-bindings`` in an isolated build, constrain it with ``PIP_CONSTRAINT``. A build with ``--no-build-isolation`` uses the installed ``cuda-bindings``. Use the repository's `Recommended clone `_ recipe below. On native Windows outside WSL, complete its Windows setup *before* cloning so Git can create the build-critical ``cuda_core/_build_shared.py`` symlink. .. code-block:: console $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git $ cd cuda-python/cuda_core $ pip install . .. note:: ``--recurse-submodules`` is required: the build compiles against the CCCL headers pinned in the ``cuda_core/third_party/cccl`` submodule, and fails without them. For a clone that already exists, run the following from the repository root: ``git submodule update --init cuda_core/third_party/cccl``. .. note:: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``cuda-core-v*`` tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository `_ for details. Development with uv ~~~~~~~~~~~~~~~~~~~ `uv`_ is a fast Python package and project manager. Before cloning, check the :ref:`source-build prerequisites `. For example, to work on ``cuda-core`` against CUDA 13: .. code-block:: console $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git $ cd cuda-python/cuda_core $ uv venv $ source .venv/bin/activate # On Windows: .venv\Scripts\activate $ uv pip install -e .[cu13] --group test Run tests: .. code-block:: console $ python -m pytest tests .. _uv: https://docs.astral.sh/uv/ Development with pixi ~~~~~~~~~~~~~~~~~~~~~ `pixi`_ provides a reproducible development environment across the repository. Before cloning, check the :ref:`source-build prerequisites `. For example, to work against CUDA 13: .. code-block:: console $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git $ cd cuda-python $ pixi run -e cu13 test-core To run all repository tests (pathfinder → bindings → core): .. code-block:: console $ pixi run -e cu13 test Use ``-e cu12`` to test against CUDA 12 instead. .. _pixi: https://pixi.sh/